Table of Contents

Next Page

Professional Apache Geronimo
Professional Apache Geronimo
byJeff Genender, Bruce SnyderandSing Li
Wrox Press 2007 (494 pages)
ISBN:0471785431

Packed with numerous examples of configuration and deployment for the Geronimo server, this book shows readers how to download and install Geronimo, use its available tools, administer and manage its servers, and configure and deploy its applications.

Table of Contents
 | Professional Apache Geronimo
 | Credits
 | Introduction
 | Chapter 1 | - | Getting Started with Geronimo
 | Chapter 2 | - | Basic Geronimo Configuration
 | Chapter 3 | - | Apache and Geronimo
 | Chapter 4 | - | Geronimo’s J2EE 1.4 Components
 | Chapter 5 | - | Geronimo Architecture and Directory Structure
 | Chapter 6 | - | The Geronimo Deployer
 | Chapter 7 | - | Using the Geronimo Debug Console and jconsole
 | Chapter 8 | - | Geronimo Web Console
 | Chapter 9 | - | Geronimo Deployment Plans
 | Chapter 10 | - | Web Container Configuration and Jetty
 | Chapter 11 | - | Tomcat Web Container Configuration
 | Chapter 12 | - | Deploying Enterprise Applications (EAR) with OpenEJB
 | Chapter 13 | - | Configuring and Deploying JDBC Resources with PostgreSQL
 | Chapter 14 | - | Deploying Web Services and CORBA Interoperation
 | Chapter 15 | - | Security
 | Chapter 16 | - | Configuring, Deploying, and Using JMS Resources with Apache ActiveMQ
 | Appendix A | - | Geronimo Deployment Plans Cross-Reference
 | Appendix B | - | Run-Time Deployer Command Reference
 | Index
 | List of Figures
 | List of Tables
 | List of Listings

Next Page


Back Cover

Previous Page
Next Page

Back Cover

Geronimo is a popular production-grade Open Source J2EE 1.4 certified server available free of charge. It is the only server of its kind licensed under the Apache Software License 2.0, allowing free adaptation and modification for commercial or non-commercial use. The server is well-supported internationally by a large base of users, developers, and support vendors. Geronimo can host a variety of server applications. It comes equipped with a relational database server and message broker, enabling you to immediately deploy your enterprise applications.

With all this potential, getting started with Geronimo can be a daunting task. This team of experienced authors has crafted a book to make your experience with Geronimo go smoothly - and they've packed it with numerous examples of configuration and deployment for the Geronimo server. Whether you've been using a commercial J2EE server or this is your first encounter with an application server, you'll quickly learn what Geronimo can do for your environment.

What you will learn from this book

  • How to configure and deploy a J2EE application on Geronimo
  • Ways to download, install, configure, and secure the server
  • Expert tips on server customization and tuning
  • How to use the various administrative, management, and troubleshooting tools that accompany Geronimo
  • How to take advantage of the highly modular architecture of the Geronimo server, and how it works inside

Who this book is for

This book is for managers, administrators, and developers who are either considering Geronimo for possible production deployment, or are already using Geronimo and are looking for a way to kick-start the implementation process.

About the Authors

Jeff Genender has more than 17 years of software architecture, team lead, and development experience in multiple industries. He is a frequent speaker on topics pertaining to Enterprise Service Buses (ESBs), Service Oriented Architecture (SOA), and application servers. Jeff is an active committer and Project Management Committee (PMC) member for Apache Geronimo, as well as a committer on OpenEJB, ServiceMix, and Mojo (Maven plugins). Jeff also serves as a member of the Java Community Process (JCP) expert group for JSR-244 (Java Platform, Enterprise Edition 5 [Java EE 5] Specification) as a representative of the Apache Software Foundation. Jeff is an Open Source evangelist and has successfully brought Open Source development efforts, initiatives, and success stories into a number of Global 2000 companies, saving these organizations millions of dollars in licensing costs.

Bruce Snyder is a 10-year veteran of enterprise software development and a recognized leader in Open Source software. Bruce has experience in a wide range of technologies, including Java Enterprise Edition (EE), Service Oriented Architecture (SOA), and Enterprise Service Buses (ESBs). In addition to his role as a senior architect for LogicBlaze, Bruce is also a founding member of Apache Geronimo and a developer for Apache ActiveMQ, Apache ServiceMix, and Castor, among other things. Bruce also serves as a member of a few JCP expert groups JSR-221 (JDBC 4.0), JSR-243 (Java Data Objects 2.0) and JSR-291 (Dynamic Component Support for Java). In addition, Bruce is also a speaker at industry conferences, including The ServerSide Java Symposium, Java in Action, JavaOne, ApacheCon, JAOO, SOA Web Services Edge, No Fluff Just Stuff, and various Java user groups.

Sing Li (who was bitten by the microcomputer bug in the late 1970s) has grown up with the Microprocessor Age. His first personal computer was a $99 do-it-yourself Netronics COSMIC ELF computer with 256 bytes of memory, mail ordered from the back pages of Popular Electronics magazine. A 20-year industry veteran, Sing is a system developer, Open Source software contributor, and freelance writer specializing in Java technology and embedded and distributed systems architecture. He regularly writes for several popular technical journals and e-zines, and is the creator of the “Internet Global Phone,” one of the very first Internet phones available. He has authored and coauthored a number of books across diverse technical disciplines including Geronimo, Tomcat, JSP, servlets, XML, Jini, media streaming, device drivers, and JXTA.

Previous Page


Professional Apache Geronimo

Jeff Genender,
Bruce Snyder,
Sing Li
Image from book
Wiley Publishing, Inc.

Published by
Wiley Publishing, Inc.
10475 Crosspoint Boulevard
Indianapolis, IN 46256
www.wiley.com

2007 by Wiley Publishing, Inc., Indianapolis, Indiana

Published simultaneously in Canada

ISBN-13: 978-0-471-78543-9

ISBN-10: 0471785431

Manufactured in the United States of America

10 9 8 7 6 5 4 3 2 1

1B/RQ/RQ/QW/IN

Library of Congress Catalogue Control Number: 2006026766

No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, scanning or otherwise, except as permitted under Sections 107 or 108 of the 1976 United States Copyright Act, without either the prior written permission of the Publisher, or authorization through payment of the appropriate per-copy fee to the Copyright Clearance Center, 222 Rosewood Drive, Danvers, MA 01923, (978) 750-8400, fax (978) 646-8600. Requests to the Publisher for permission should be addressed to the Legal Department, Wiley Publishing, Inc., 10475 Crosspoint Blvd., Indianapolis, IN 46256, (317) 572-3447, fax (317) 572-4355, or online at http://www.wiley.com/go/permissions.

LIMIT OF LIABILITY/DISCLAIMER OF WARRANTY: THE PUBLISHER AND THE AUTHOR MAKE NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE ACCURACY OR COMPLETENESS OF THE CONTENTS OF THIS WORK AND SPECIFICALLY DISCLAIM ALL WARRANTIES, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE. NO WARRANTY MAY BE CREATED OR EXTENDED BY SALES OR PROMOTIONAL MATERIALS. THE ADVICE AND STRATEGIES CONTAINED HEREIN MAY NOT BE SUITABLE FOR EVERY SITUATION. THIS WORK IS SOLD WITH THE UNDERSTANDING THAT THE PUBLISHER IS NOT ENGAGED IN RENDERING LEGAL, ACCOUNTING, OR OTHER PROFESSIONAL SERVICES. IF PROFESSIONAL ASSISTANCE IS REQUIRED, THE SERVICES OF A COMPETENT PROFESSIONAL PERSON SHOULD BE SOUGHT. NEITHER THE PUBLISHER NOR THE AUTHOR SHALL BE LIABLE FOR DAMAGES ARISING HERE-FROM. THE FACT THAT AN ORGANIZATION OR WEBSITE IS REFERRED TO IN THIS WORK AS A CITATION AND/OR A POTENTIAL SOURCE OF FURTHER INFORMATION DOES NOT MEAN THAT THE AUTHOR OR THE PUBLISHER ENDORSES THE INFORMATION THE ORGANIZATION OR WEBSITE MAY PROVIDE OR RECOMMENDATIONS IT MAY MAKE. FURTHER, READERS SHOULD BE AWARE THAT INTERNET WEBSITES LISTED IN THIS WORK MAY HAVE CHANGED OR DISAPPEARED BETWEEN WHEN THIS WORK WAS WRITTEN AND WHEN IT IS READ.

For general information on our other products and services please contact our Customer Care Department within the United States at (800) 762-2974, outside the United States at (317) 572-3993 or fax (317) 572-4002.

Trademarks: Wiley, the Wiley logo, Wrox, the Wrox logo, Programmer to Programmer, and related trade dress are trademarks or registered trademarks of John Wiley & Sons, Inc. and/or its affiliates, in the United States and other countries, and may not be used without written permission. All other trademarks are the property of their respective owners. Wiley Publishing, Inc., is not associated with any product or vendor mentioned in this book.

Wiley also publishes its books in a variety of electronic formats. Some content that appears in print may not be available in electronic books.

Dedication

From Jeff:

This is dedicated to my wife Nazarena, my daughter Madisyn, and my two sons, Weston and Coleton, who have supported me unconditionally throughout my career.

From Bruce:

To Janene - my friend, my love, my life.

From Sing:

To my sole source of energy for the past two decades, Kim.

From all of us:

To the tireless team at Wiley, performing their magic to make this book a reality. Thanks to Kevin Shafer, our development editor, for his infinite patience with delayed manuscripts; to Bob Elliot for his faith on our book concept; to Tom Dinse and the production team, for transforming our rough notes into this finished book.

About the Authors

Jeff Genender

Jeff Genender has more than 17 years of software architecture, team lead, and development experience in multiple industries. He is a frequent speaker on topics pertaining to Enterprise Service Buses (ESBs), Service Oriented Architecture (SOA), and application servers. Jeff is an active committer and Project Management Committee (PMC) member for Apache Geronimo, as well as a committer on OpenEJB, ServiceMix, and Mojo (Maven plugins). Jeff also serves as a member of the Java Community Process (JCP) expert group for JSR-244 (Java Platform, Enterprise Edition 5 [Java EE 5] Specification) as a representative of the Apache Software Foundation. Jeff is an Open Source evangelist and has successfully brought Open Source development efforts, initiatives, and success stories into a number of Global 2000 companies, saving these organizations millions of dollars in licensing costs.

Bruce Snyder

Bruce Snyder is a 10-year veteran of enterprise software development and a recognized leader in Open Source software. Bruce has experience in a wide range of technologies, including Java Enterprise Edition (EE), Service Oriented Architecture (SOA), and Enterprise Service Buses (ESBs). In addition to his role as a senior architect for LogicBlaze, Bruce is also a founding member of Apache Geronimo and a developer for Apache ActiveMQ, Apache ServiceMix, and Castor, among other things. Bruce also serves as a member of a few JCP expert groups JSR-221 (JDBC 4.0), JSR-243 (Java Data Objects 2.0) and JSR-291 (Dynamic Component Support for Java). In addition, Bruce is also a speaker at industry conferences, including The ServerSide Java Symposium, Java in Action, JavaOne, ApacheCon, JAOO, SOA Web Services Edge, No Fluff Just Stuff, and various Java user groups.

Sing Li

Sing Li (who was bitten by the microcomputer bug in the late 1970s) has grown up with the Microprocessor Age. His first personal computer was a $99 do-it-yourself Netronics COSMIC ELF computer with 256 bytes of memory, mail ordered from the back pages of Popular Electronics magazine. A 20-year industry veteran, Sing is a system developer, Open Source software contributor, and freelance writer specializing in Java technology and embedded and distributed systems architecture. He regularly writes for several popular technical journals and e-zines, and is the creator of the “Internet Global Phone,” one of the very first Internet phones available. He has authored and coauthored a number of books across diverse technical disciplines including Geronimo, Tomcat, JSP, servlets, XML, Jini, media streaming, device drivers, and JXTA.


Credits

Executive Editor
Robert Elliott

Development Editor
Kevin Shafer

Production Editor
Felicia Robinson

Copy Editor
Foxxe Editorial Services

Editorial Manager
Mary Beth Wakefield

Production Manager
Tim Tate

Vice President and Executive Group Publisher
Richard Swadley

Vice President and Executive Publisher
Joseph B. Wikert

Graphics and Production Specialists
Jonelle Burns
Carrie Foster
Denny Hager
Barbara Moore
Heather Ryan
Alicia B. South

Quality Control Technicians
Robert Springer
Brian H. Walls

Proofreading and Indexing
Techbooks


Introduction

Apache Geronimo is the first Open Source Java 2 Enterprise Edition (J2EE) 1.4 certified application server released under the liberal Apache 2.0 License. The availability of a production-grade J2EE server to the general public free of charge, and free of technical or financial obligations, is unprecedented. Geronimo is a robust server that is well supported by a large global community of users and developers.

As a full-featured J2EE server, Geronimo can host a variety of server applications, including those created using servlets, Java Server Pages (JSPs), Enterprise JavaBeans (EJBs), and Message Driven Beans (MDBs). In addition, Geronimo provides valuable container services, including naming/lookup, security, management, and transaction. Geronimo also comes out of the box with a relational database server and a message queue broker. You can immediately deploy your enterprise application to Geronimo.

Getting started with such a comprehensive server can be a daunting undertaking. This book is written to make this easy. Whether you have been using a commercial J2EE server, or this is your first encounter with an application server, this book should make your exploration and implementation as smooth and painless as possible.

Who This Book is For

This book is ideal for those considering Geronimo for possible production deployment within their organizations. Those who had already decided on Geronimo, and want the most rapid ramp-up possible to kick-start the implementation process, will find great value here. Whether you are a manager looking for information to aid in your decision making, a system administrator looking for deployment and configuration information, or a developer evaluating Geronimo for in-house testing and/or production development, you will find that this book provides an effective one-stop shop for your Geronimo needs.

Managers will benefit from the conceptual and architectural coverage that familiarizes you with how things work in Geronimo. Limitations and deployment considerations are cited where applicable to provide a feel of what Geronimo can really do for you in your environment.

Administrators will find the hands-on deployment and configuration examples useful. A cookbook approach covers all the target modules and packages that you may want to deploy to a Geronimo server, including download, installation, configuration, deployment, as well as server management and maintenance-all aspects of Geronimo.

Developers will find the organization of the book clean and concise enough to dive into applicable sections to quickly extract usable information. Written by hardcore developers who wrote some of the actual Geronimo code, the authors understand the needs of developers, and the coverage in this book reflects it. Chapters and sections on application troubleshooting, the chapter on Geronimo’s “secret” debug console, and jconsole integration are just a short list of examples of the hardcore coverage that this book provides.


What This Book Covers

This book covers Release 1.1 of the Apache Geronimo server. Release 1.1 is a major feature-complete release of the Geronimo server. Moving forward, new 1.x releases will maintain the same configuration and deployment features. Because of this, the techniques and examples covered in this book should be applicable to most 1.x releases.

Many bugs were fixed in Release 1.1. Almost all production users of Geronimo will be using Release 1.1 or later. Release 1.0 has significantly different deployment syntax and is not supported directly by this book.


Features of This Book

This book is packed full of configuration and deployment examples for the Geronimo server.

Key features of this book include the following:

  • Deployment and configuration coverage for all J2EE module types

  • Server and module configuration techniques from the creators of Geronimo

  • In-depth coverage of Geronimo’s security infrastructure

  • Hands-on deployment examples help you hit the ground running

  • Customization and tuning tips Geronimo for your specific requirements

  • Up-to-date coverage of Geronimo 1.1 features and beyond

  • A true insider’s perspective on the architecture and design of the Geronimo server

This book is written by individuals who live, breathe, and eat everything Geronimo. The companion Web site, described later, provides extensive supplements, updates, and support for the material in this book.

This book is quintessential reading for all Geronimo administrators and developers.


How This Book is Structured

The book is structured to get you started working with Geronimo in the shortest possible time. It is divided into three parts. The first couple of chapters covers download, installation, testing, and initial deployment of a J2EE application on the Geronimo server.

Once you are up to speed, you take a little time off to investigate Geronimo’s history, architecture, operations, and how all the components and configuration files fit together. This part of the reading is most applicable to readers evaluating Geronimo. You can skip directly to this section if you do not need the hands-on installation and deployment exercise.

The third part of the book covers the administrative, management, and troubleshooting tools supplied with Geronimo, and each of the J2EE deployable modules in more detail. A chapter is devoted to each important topic. There are many deployment and configuration examples throughout this section that you can customize for your specific scenario.

Advanced Geronimo topics are covered in additional bonus chapters that you can download from the companion Web site. Updates to chapters in this printed book can also be found on the companion Web site.

The following is a description of the chapters in this book:

  • Chapter 1 , “ Getting Started with Geronimo ,” covers the hardware and software that you need to have before installing Geronimo, as well as the download and installation of the Apache Geronimo server. The different available downloads are explained, and the chapter guides you through a hands-on installation. You will have a working Geronimo application server running by the end of this chapter.

  • Chapter 2 , “ Basic Geronimo Configuration ,” guides you through the hands-on configuration and deployment of an enterprise application to the Geronimo server. You deploy an application consisting of servlet, JSP, and EJB components. This chapter shows how to override the default configuration of Geronimo server, and how to use the command-line deployer, as well as the Web console to deploy modules and monitor server status.

  • Chapter 3 , “ Apache and Geronimo ,” provides historical information on the Geronimo project. The chapter describes the heritage and excellence of its originator-the Apache Software Foundation. The events that led from concept to actual release of the server are presented. The different types of Open Source licenses and how they may affect your application are also explored.

  • Chapter 4 , “ Geronimo’s J2EE 1.4 Components ,” provides an overview of the components comprising the Geronimo server from a J2EE perspective. The different J2EE tiers, the container at each tier, and the individual container services are explored in detail. The interaction between deployed software modules and Geronimo at each tier is also explained.

  • Chapter 5 , “ Geronimo Architecture and Directory Structure ,” examines the architecture and operations of the Geronimo server. This chapter puts into perspective the components introduced in Chapter 4, and shows how they work during the operation of the server. The internal working of the Geronimo server is explored. The on-disk directory organization of Geronimo is presented, and the purpose of each of the directories is described. You will learn about the location of the various configuration files, and you will become familiar with Geronimo’s repository.

  • Chapter 6 , “ The Geronimo Deployer ,” provides comprehensive coverage of the most commonly used tool in Geronimo. Every available command and option is covered. A brief discussion of how the deployer tool works and how it works with JSR-88–complaint deployment systems is presented.

  • Chapter 7 , “ Using the Geronimo Debug Console and jconsole ,” reveals a versatile, yet little-known, debug tool for Geronimo. Using the debug tool enables you to look inside a running instance of Geronimo and see all the objects that are running. The JSR-77–compatible object naming convention used internally by Geronimo is explained. For readers running on JDK 5, the chapter shows how the jconsole utility from Java Developer’s Kit (JDK) 5 can also be used to examine server states and monitor server operations.

  • Chapter 8 , “ Geronimo Web Console ,” covers the use and operation of Geronimo’s GUI Web console. From startup to shutdown, each option and menu of the console is examined. You will become fluent with the use of this essential tool. Wherever applicable, coverage is provided to show how to do the equivalent operation using manual command-line tools. This approach ensures that you can get your deployment and configuration done even if you cannot start the Web console.

  • Chapter 9 , “ Geronimo Deployment Plans ,” is a chapter that enumerates and explains each of the deployment plans that you may use when deploying J2EE application modules to Geronimo. With many different kinds of deployable modules available, and each module containing both mandatory and optional deployment plans, a large number of possible plans exist. This chapter classifies them and explains where each one may be used.

  • Chapter 10 , “ Web Container Configuration and Jetty ,” examines the deployment and configuration of Web applications in the Geronimo server. The focus of this chapter is on the general deployment of Web application modules, and also the configuration of the Jetty container. The Jetty container has container-specific features (such as virtual hosting) that can be configured via Geronimo deployment plans. This chapter shows all the Jetty-specific configuration options.

  • Chapter 11 , “ Tomcat Web Container Configuration ,” follows up from Chapter 10 and provides details on how to configure the Tomcat Web application container using Geronimo deployment plans. Tomcat-specific features (such as realms, filters, and valves) can be configured with virtual hosting support. You will also see how the Geronimo container managed security system can be configured to work with the Tomcat server.

  • Chapter 12 , “ Deploying Enterprise Applications (EAR) with OpenEJB ,” explores the deployment of enterprise applications, including EJBs. Both session beans and entity beans are covered, including the deployment of EJB 2.1 supported Container Managed Persistence (CMP) beans. You will work hands-on with the required deployment plans. This chapter also reveals how you can configure Geronimo to enable JavaMail support, allowing your EJBs and applications to send and receive email. The chapter also contains a brief discussion of Geronimo’s Client Application Container.

  • Chapter 13 , Configuring and Deploying JDBC Resources with PostgreSQL ,” examines the configuration and deployment of application that make connections to relational databases, including EJB, which relies on CMP to access relational database management systems (RDBMSs). Coverage includes the deployment of database pools and drivers via a Resource Adapter Archive (RAR)-allowing Geronimo-hosted applications to access external RDBMS servers. A hands-on example using the robust PostgreSQL is presented.

  • Chapter 14 , “ Deploying Web Services and CORBA Interoperation ,” provides a working hands-on example showing how to expose servlets and EJBs as Web services in Geronimo. These Web services can be accessed from a variety of clients, including .NET and scripting clients such as Python or PHP. It also shows how EJBs in an application can be exposed as Common Object Request Broker Architecture (CORBA) servers-enabling access to your J2EE application from legacy systems. The configurable CSI v2 interoperable security architecture from CORBA is also explained in this chapter.

  • Chapter 15 , “ Security ,” explains the security infrastructure in the Geronimo server. Fundamental concepts including security realms, login modules, and login domains are covered. The authentication and authorization needs of applications are examined, and the Java Authentication and Authorization Service (JAAS) and Java Authorization Contract for Containers (JACC) based implementation are revealed. Details will be provided for the available security descriptors, and where and how they can be used within Geronimo deployment plans.

  • Chapter 16 , “ Configuring, Deploying, and Using JMS Resources with ActiveMQ ,” is a chapter devoted to the deployment of modules for applications using message queues (MQs). The architecture of the ActiveMQ message broker, included as part of Geronimo, is presented. Customization and general configuration of this versatile MQ server is illustrated through several example configurations. Application-level resource adapter deployment is demonstrated through a hands-on example.

  • Appendix A , “ Geronimo Deployment Plans Cross-Reference ,” is a summary of the different Geronimo-specific deployment plans that you may use in the module. It provides just enough information on the structure of the plan to kick-start your configuration effort. This appendix is designed to be used in conjunction with Geronimo reference documentation or the DTD/ Schema of the associated plan. (This appendix tells you where to find these DTD and schemas.)

  • Appendix B , “ Run-Time Deployment Command Reference ,” is a command and option reference for the command line-deployment tool. This appendix can be a handy reference when you deploy and manage application modules on your Geronimo servers.


What You Need to Use This Book

It is possible to go through this book and learn a great deal about Geronimo, its architecture, its design, and its operation without the need to try out any of the examples.

However, if you want to try out the hands-on configuration and deployment examples, you need a system with at least 1GB of RAM, 500MB or more of available storage, and a 2 GHz or faster processor (or equivalent). You will also need to have the latest version of JDK 1.4 or JDK 5 installed and running on the system before installing Geronimo.

The system you use must be networked (have a network adapter properly configured), and ideally be connected to the Internet (for downloads) at high speed.


Conventions

To help you get the most from the text and keep track of what’s happening, we’ve used a number of conventions throughout the book.

Important

Boxes like this one hold important, not-to-be forgotten information that is directly relevant to the surrounding text.

Tips, hints, tricks, and asides to the current discussion are offset and placed in italics like this.

As for styles in the text:

  • We highlight important words when we introduce them.

  • We show keyboard strokes like this: Ctrl+A.

  • We show filenames, URLs, and code within the text like this: persistence.properties.

  • We present code in two different ways:

In code examples we highlight new and important code with a gray background.

The gray highlighting is not used for code that's less important in the present
context, or has been shown before.


Source Code

As you work through the examples in this book, you may choose either to type in all the code manually or to use the source code files that accompany the book. All of the source code used in this book is available for download at www.wrox.com. Once at the site, simply locate the book’s title (either by using the Search box or by using one of the title lists) and click the Download Code link on the book’s detail page to obtain all the source code for the book.

Because many books have similar titles, you may find it easiest to search by ISBN; for this book the ISBN is 0-471-78543-1.

Once you download the code, just decompress it with your favorite compression tool. Alternately, you can go to the main Wrox code download page at www.wrox.com/dynamic/books/download.aspx to see the code available for this book and all other Wrox books.


Errata

We make every effort to ensure that there are no errors in the text or in the code. However, no one is perfect, and mistakes do occur. If you find an error in one of our books (such as a spelling mistake or faulty piece of code), we would be very grateful for your feedback. By sending in errata, you may save another reader hours of frustration and, at the same time, you will be helping us provide even higher-quality information.

To find the errata page for this book, go to www.wrox.com and locate the title using the Search box or one of the title lists. Then, on the book details page, click the Book Errata link. On this page you can view all errata that has been submitted for this book and posted by Wrox editors. A complete book list including links to each book’s errata is also available at www.wrox.com/misc-pages/booklist.shtml.

If you don’t spot “your” error on the Book Errata page, go to www.wrox.com/contact/techsupport.shtml and complete the form there to send us the error you have found. We’ll check the information and, if appropriate, post a message to the book’s errata page and fix the problem in subsequent editions of the book.


www.progeronimo.com

Many authors of this book live and breathe Geronimo. They are the committers on the Geronimo project and write or maintain Geronimo server code on a daily basis. The companion Web site, www.progeronimo.com, is where you will find the latest updates on Geronimo directly from the authors.

Here, you will find updates to examples in the book as Geronimo evolves through its 1.x releases. You will also find bonus chapters covering additional advanced Geronimo topics at this site ready for your download.

On this site the authors will make timely Geronimo related announcements of interest to the readership. This will be the primary site for updates for this book until the second edition becomes available.

For a more interactive experience, p2p.wrox.com is available.


p2p.wrox.com

For author and peer discussion, join the P2P forums at p2p.wrox.com. The forums are a Web-based system for you to post messages relating to Wrox books and related technologies and interact with other readers and technology users. The forums offer a subscription feature to email you topics of interest of your choosing when new posts are made to the forums. Wrox authors, editors, other industry experts, and your fellow readers are present on these forums.

At http://p2p.wrox.com you will find a number of different forums that will help you not only as you read this book but also as you develop your own applications. To join the forums, just follow these steps:

  1. Go to p2p.wrox.com and click the Register link.

  2. Read the terms of use and click Agree.

  3. Complete the required information to join, as well as any optional information you wish to provide, and click Submit.

  4. You will receive an email with information describing how to verify your account and complete the joining process.

You can read messages in the forums without joining P2P, but to post your own messages, you must join.

Once you join, you can post new messages and respond to messages other users post. You can read messages at any time on the Web. If you would like to have new messages from a particular forum emailed to you, click the “Subscribe to this Forum” icon by the forum name in the forum listing.

For more information about how to use the Wrox P2P, be sure to read the P2P FAQs for answers to questions about how the forum software works, as well as many common questions specific to P2P and Wrox books. To read the FAQs, click the FAQ link on any P2P page.


Chapter 1: Getting Started with Geronimo

Overview

The goal of this chapter is to get Geronimo up and running for your own system in the shortest possible time. The basic system requirements, on both Unix and Windows systems will be revealed. Step-by-step installation is provided. Potential problems encountered during Geronimo installation and setup are pointed out, and we will share some of our solutions with you.

In this chapter, you will:

  • Discover where to download Geronimo releases and updates

  • Learn about which distribution to download and why

  • Ascertain that your system is capable of running Geronimo and learn where to find the additional system requirements if needed

  • Install a Geronimo server on your system

  • Successfully start up and test the server

By the end of this chapter, you will have the information and confidence that you need to install and set up Geronimo servers in your own work environment. You will be ready to start deploying applications on your server.


Where to Find Geronimo

Geronimo is a top-level project at the Apache Software Foundation Web site. The headquarters for all your Geronimo needs is located at the following URL:

http://geronimo.apache.org

On this site, you will find the following:

  • The latest Geronimo binaries

  • The latest Geronimo source

  • Geronimo documentation

  • The latest Geronimo news and resources

  • An active Geronimo developer community

The remainder of this chapter shows how to leverage the use of many of these resources.

Figure 1-1 shows the home page of the Geronimo project.

Image from book
Figure 1-1: Geronimo project home page

As you can see in Figure 1-1, you can find links to the latest software download and documentation by selection one of the tabs at the top of the home page. When you click on the Download tab, there are numerous download choices. Figure 1-2 shows some of the available download choices.

Image from book
Figure 1-2: Geronimo download page

The next section will help you decide on what to download.

Geronimo Build and Releases

Geronimo is a very large project that is created by a geographically diverse team of international Open Source developers. Because of time zone differences, development continues around the clock. The software team creates releases of software on a regular basis to synchronize work. To track all the development changes, a version control system called Subversion is used. As a result, you will frequently hear about builds and releases at the Geronimo Web site.

Builds can be considered as trial releases of the software. A build is a compilation of the project at a specific time. With the Geronimo project, a build occurs every evening, 365 days a year. As a result, you will find that build numbers can become very large.

Releases are certain builds that are considered major deliverables in the Geronimo project. It takes great effort from the development team to coordinate a release of the software. There are only a few releases of the Geronimo software thus far (1.0, 1.1, and so on).

Users are typically concerned only with releases. However, to get the latest feature or bug fix, you may have to download and install the latest build between releases. From time to time, the Geronimo team may elect to make certain builds available for download. In general, the most important builds of Geronimo are summarized in Table 1-1.

Table 1-1: Geronimo Builds Open table as spreadsheet
Build | Description
Latest unstable build | This is the last successful daily build. It always contains the latest features and bug fixes. However, it is not of release quality and has not been extensively tested. Use these builds at your own risk.
Latest milestone build | Before the availability of the first major release of Geronimo, a set of product features are made available to early-adopter users via milestone builds. Milestone builds are well-tested releases of the software but with only a subset of features of major releases. You will not see Geronimo milestone builds available for download anymore. This description is provided for historical reasons, and you may see some Geronimo literature referring to milestone builds.

The first Java 2 Enterprise Edition (J2EE) 1.4–complaint release of Geronimo is release 1.0. However, since the release of 1.0, Geronimo users all over the world have discovered and reported various bugs. In addition, the Geronimo team made significant configuration and architecture improvements to the server. All of this work cumulates in the release of Geronimo 1.1 - the first stable version of Geronimo ready for production deployment. This book covers the features of Geronimo 1.1 extensively.

Important

Since Geronimo has reached release 1.1 level, you may no longer see any downloads for Geronimo builds on the Geronimo site. This is normal, because the Geronimo team has elected to produce frequent releases instead of making intermediate builds available.

You should always download a Release 1.1 or later from the Geronimo Web site. Table 1-2 shows some of the current and prior Geronimo releases.

Table 1-2: Available Geronimo Releases Open table as spreadsheet
Release | Description
1,1 | A much improved version of 1.1. Other than fixing major bugs, this release also has enhanced features such as support for plug-ins, support for a small footprint Little-G distribution. The module configuration notation has changed significantly in 1.1. With the availability of release 1.1, there is very little reason to work with 1.0 of the server.
1.0 | The first fully J2EE 1.4–compliant release. Extensively tested.
M5 - Milestone 5 | A release candidate milestone build. All of the features in release 1.0 are included. This build is extensively tested. M5 is almost release quality and was used in limited production before release 1.0 is available.
M4 - Milestone 4 | First usable build for general users. Extensively tested. Can be used to deploy most enterprise applications. Useful for early-adopter users.
M3 and before | These builds are missing major features. They were used mainly to provide development users with early access to the software base. Do not use these builds for production under any circumstances.

Binary versus Source Download

Once you have decided on a release, you can select from the type of distributions available:

  • Binary

  • Source code

A binary distribution contains all the executables you need to run a Geronimo server. Binary distributions are typically packaged in ZIP format for Windows and tar-gzip (tar.gz) format for Unix operating systems.

The source code distribution is typically of interest only to Geronimo system developers who want to modify the source code.

Important

Advanced user of Geronimo may sometimes use the source code distribution to build their own customized version of the Geronimo or to customize the capabilities of the server. In fact, we will share some of our own Geronimo customization tips in Bonus Downloadable Chapter 18, The Essence of Geronimo: Flexible Assemblies, at www.progeronimo.com .

Jetty versus Tomcat Binary Downloads

When you arrive at the Geronimo download page, you will be provided with a choice of downloading a binary distribution of Geronimo with either the Jetty Web-tier container or the Tomcat Web-tier container. You only need to choose one of these downloads.

Geronimo as a J2EE server supports two alternative Web-tier containers: Jetty and Tomcat. The latest available version of Jetty and Tomcat, at the time of release, is typically included with the distribution. For example, Geronimo 1.1 includes Tomcat 5.5.15 or Jetty 5.1.10.

Both Jetty and Tomcat are matured Open Source containers for running servlets and Java Server Pages (JSPs). Chances are that you or your company is already using one of these Web-tier application containers, and the choice will be clear.

If you want to find out more about these Web-tier containers, the following is the link to Jetty:

http://jetty.mortbay.org

The link to Tomcat, another Apache project, is at the following URL:

http://tomcat.apache.org

Full Installation versus Minimal Little-G Server

Release 1.1 of Geronimo supports two special very small footprint versions of the server, known among the developers as Little-G:

  • Little-G 1.1 with Tomcat

  • Little-G 1.1 with Jetty

Each of these Little-G servers is stripped down to the bare minimum. For example, the support for Enterprise JavaBeans (EJBs), for the Active MQ message broker, for internal relational database, for CORBA, and all sample applications are removed. This leaves only the container services (security, transaction, deployment, and so on) and a Web-tier server (either Tomcat or Jetty). The idea behind these minimal server configurations is to enable the easy construction of customized servers. Users can start with one of the Little-G servers and add just enough support for the application that they will be running.

If you are deploying applications that only contain servlets and JSPs, Little-G may be the right download for you. Applications using lightweight frameworks (such as Spring 2) can also run in Little-G. However, if you are deploying J2EE 1.4 applications that use EJB or message queues, then you will need to download the full binary distribution.

The focus of this book is on the J2EE 1.4–compatible personality of Geronimo. You will be working mostly with the full binary distribution of Geronimo. These larger server distributions contain a superset of software components and features when compared to Little-G.

All the techniques you learn in this book will apply equally to the regular full-sized distributions, as well as the Little-G minimal server distributions.


Before Installing Geronimo

Ensure that you have met all the hardware and software requirements before you install Geronimo. This section can help you to plan your systems for wide deployment of Geronimo.

Hardware Platform Requirements

Geronimo has been tested and runs well on any x86 platform. From our experience, you should really have a processor with speed of 2 GHz and above for serious production deployment. Being a Java-based server, you are not tied to x86 processors. Geronimo has been tested on PowerPC (Mac OS), Sparc (SUN Solaris), as well as PA-RISC (HP-UX) processors.

Important

As with all J2EE 1.4–compatible servers, the compatibility testing is performed on a highly version-specific software stack (that is, a certain operating system release level with certain Java VM release level, and so on). If you are required to run only on 100 percent J2EE 1.4 certified platform, you must duplicate the certified stack and acquire your hardware based on it. See the following URL for more information on J2EE 1.4 compatibility: http://java.sun.com/j2ee/compatibility_1.4.html

A basic Geronimo configuration (such as the Little-G servers) can be started on systems with as little as 256MB of RAM. To get reasonable performance, it is recommended that you start your production Geronimo server at 1GB of RAM.

Needless to say, you will need a network connection on the server machine. Adapters for gigabits, 100 Mbps, or even 10 Mbps will work fine for most Geronimo configurations.

JVM Requirement

In general, you will require Java Development Kit (JDK) 1.4.2 to successfully run Geronimo. More particularly, you will need SUN’s Java Virtual Machine (JVM) to run release 1.1 of Geronimo if you need to support Common Object Request Broker Architecture (CORBA). This restriction is because of some internal dependency of this release of Geronimo on the Object Request Broker (ORB) included with SUN’s JDK.

To eliminate the stranglehold of the non–Open Source ORB, veterans from the original Geronimo team are busy working with on the Yoko project in the Apache incubator (the stage of development when startup Open Source projects go through initial incubation). The Yoko project aims to create a complete standards-compliant, Open Source CORBA ORB. When the ORB is finished, it will be integrated in Geronimo - eliminating the need for SUN’s JDK. You can find out a lot more about the Yoko project at its own Apache project page:

http://incubator.apache.org/projects/yoko.html

If you do not use any CORBA features, you can run Geronimo on non–SUN JDK 1.5, as well as any compatible version of JDK 5.

Throughout this book, it is assumed that you are running Geronimo with the latest available release of JDK 1.4.2 or JDK 5. For the CORBA configuration and support example in Chapter 14, you are required to run under SUN’s JDK 1.4.2. If you do not already have SUN’s JDK 1.4.2 installed on your system, you can download it from the following URL:

http://java.sun.com/j2se/1.4.2/download.html

The latest version (as of this writing) is 1.4.2_12, and has been tested to fully support Geronimo.

Important

If you are using Mac OSX, the latest Apple JVM 1.4.2 version on OSX should support Geronimo.

As a reminder, you can always find out what version of the Java VM you have installed using the following command at the console:

java -version


Installing the Geronimo Server

The exact installation procedure depends on which binary distribution you have downloaded and also on your host operating system. In all cases, you need to preselect the directory on your machine that you will install the server on.

For the following discussion, it is assumed that you are installing the server on:

  • c:\geronimo - For the Windows operating system

  • /home/jeff/geronimo - For an Unix system

If you have downloaded the ZIP file on a Windows machine, just unzip the distribution to your destination directory. This will create c:\geronimo\geronimo-1.1 (assuming that you are running the 1.1 release).

On an Unix system, change into your installation directory and the use the following command to unarchive the file:

tar zxvf <downloaded tar.gz file name>

This command unarchives the server’s binary into the /home/jeff/geronimo-1.1 directory.

This completes the initial installation of your Geronimo server. This installation comes with a preconfigured server that is designed to run on most system configurations.

The next sections show you how to customize this default configuration.

Customizing Geronimo after Installation

The initial installation provides a starter configuration for your Geronimo server. You can readily modify the configuration if required. This can be accomplished by editing the config.xml file.

The config.xml File

The config.xml is located in the var/config directory of your Geronimo installation. This file contains a list of modules that will be loaded and started when the Geronimo server starts up. In fact, many operations performed via the Web console (covered in Chapter 8) involve changes in this configuration file.

In addition to controlling which module is started, the file can also be used to customize some attributes of Geronimo components that are installed. This will include changing the port and hostnames/IP address of the default installation.

Generally, the Geronimo server will examine the config.xml during startup to determine the following:

  • Which modules to load and start

  • The attributes of server components (called GBeans in Geronimo) that should be overridden

Note, however, that config.xml should never be modified while Geronimo is running. This is because Geronimo may write the changed module configurations back to config.xml. Any modifications you make while Geronimo is running will be lost.

In addition, since Geronimo automates the writing of the config.xml from its own internal module configuration structure, any comments you placed in the original config.xml will also be lost after Geronimo restart. Therefore, remember to only edit config.xml when Geronimo is not running - and to make frequent backup of this file.

Important

Never edit config.xml while the Geronimo server is running. Make frequent back-ups of known-good version of this file.

As an example, the module configuration entry that configures the port and hostname of the Tomcat Web connectors is shown in the following listing:

<module name="geronimo/tomcat/1.1/car">
  <gbean name="TomcatResources"/>
  <gbean name="TomcatWebConnector">
     <attribute name="host">0.0.0.0</attribute>
     <attribute name="port">8080</attribute>
     <attribute name="redirectPort">8443</attribute>
  </gbean>
  <gbean name="TomcatAJPConnector">
     <attribute name="host">0.0.0.0</attribute>
     <attribute name="port">8009</attribute>
     <attribute name="redirectPort">8443</attribute>
  </gbean>
  <gbean name="TomcatWebSSLConnector">
     <attribute name="host">0.0.0.0</attribute>
     <attribute name="port">8443</attribute>
  </gbean>
  <gbean
name="geronimo/tomcat/1.1/car?ServiceModule=geronimo/tomcat/1.1/car,j2eeType=GBean,
name=TomcatWebContainer">
       <attribute name="catalinaHome">var/catalina</attribute>
   </gbean>
</module>

You can modify any of these values and start the server to have the host and port changed.

Any listed modules in the config.xml will be loaded and started by default. To prevent one or more of the modules from loading and starting by Geronimo, set the attribute load="false" in the <module> element. For example, if you look up the CORBA support module, with name geronimo/j2ee-corba/1.1/car, you will see the following module configuration:

<module load="false" name="geronimo/j2ee-corba/1.1/car">
<gbean name="NameServer">
<attribute name="dbDir">var/cosnaming.db</attribute>
<attribute name="port">1050</attribute>
</gbean>
<gbean name="Server">
<attribute name="args">-ORBInitRef,
NameService=corbaloc::localhost:1050/NameService</attribute>
</gbean>
<gbean name="UnprotectedServer">
<attribute name="args">-ORBInitRef,
NameService=corbaloc::localhost:1050/NameService</attribute>
</gbean>
</module>

Note the load attribute of the module is set to "false", telling the Geronimo server not to load the CORBA support module during startup. This is by default - and you definitely want to prevent the CORBA support module from loading if you are using the JDK 5 VM (Java SE 5).

Running the Geronimo Server

Once you’ve installed Geronimo using the binary archives, you can start the server. First, change directory to the installation directory that you have selected. From the installation directory, change directory to the bin subdirectory. From the bin subdirectory, type in the following command:

startup

On an Unix system, you run the startup.sh script using sh startup.sh. This will start the Geronimo server running the core J2EE services. The startup status is displayed on another console window, or in the backgroup with Unix systems. The name of each module is displayed as it is started, as well as the time it took in starting it. Once the server has started up completely, your console should look similar to Figure 1-3.

Image from book
Figure 1-3: Startup screen for server10

Table 1-3 describes some of the services that are started by Geronimo 1.1. . The port for each service will reflect any customization you may have made in config.xml. The list you see may be different if you are using versions beyond 1.1.

Table 1-3: Core J2EE Services Started by Geronimo Open table as spreadsheet
Service | Port
Geronimo Naming Service (RMI-based) | 1099
OpenEJB EJB container (ActiveIO) | 4201
Remote authentication (login) server | 4242
Tomcat container connectors | 8080 (HTTP) , 8443 (secured socket - HTTPS), and 8009 (AJP 13)
Jetty container connectors | 8080 (HTTP) and 8443 (HTTPS) and 9090 (HTTP) and 8009 (AJP 13)
JMX Remoting (Management) Connector | 9999
ActiveMQ | 61616
Derby RDBMS system | 1527
Important

To shut down your Geronimo server run the shutdown (or shutdown.sh) script from the bin subdirectory. It will prompt you with userid (enter system) and password (enter manager). You can also shut down Geronimo from the Web console (covered in Chapter 8 ).

Verifying Your Installation of Geronimo

To verify that everything is running well with your Geronimo installation, you can use the deployer tool (a tool that you will use a lot, and find out a lot more about in Chapter 6) to list all the system configurations that are a built-in part of your server.

From the bin subdirectory under your installation directory, type the following command:

deploy --user system --password manager list-modules

This is how you access the deployer tool. You must supply the username system and password manager. This is set up by the default configuration at installation.

After installation, if you need to change the password, edit the users.properties file under the <installation directory>/geronimo-1.1/var/security directory. Chapter 8 provides more details on how to use the Web console to add new administrative users.

Important

Of course, you can save the repetitive step of changing directory to the bin subdirectory if you add that directory into your PATH environment variable.

The list-modules command of the deployer tool will display all the system configurations in the server. After an initial installation, your list-modules command output should be similar to Figure 1-4.

Image from book
Figure 1-4: Output from list-modules command

Each line in Figure 1-4 represents a module deployed in the Geronimo server. The ones with a “+” sign on the left are the ones that have been started, and are currently running. The URL to some of the Web-accessible modules is also shown.

Congratulations, you have just successfully installed and run Geronimo!


Summary

In this chapter, you have successfully installed and tested Geronimo on your own system.

At the official Geronimo Web site, a variety of builds and releases of Geronimo may be available for downloading. The latest builds can be useful for accessing the latest features or bug fixes. However, production purposes, you should stick with official releases.

Geronimo can run on almost any modern machine, including x86 machines running Windows or Unix, or Linux of many flavors. Mac OSX, and Sun Solaris also support the server. You must use SUN’s JDK 1.4.2 i JVM for Geronimo if you need CORBA support. Otherwise, Geronimo works great on JDK 5 (Java SE 5).

Geronimo installation on both Windows and Unix machine can be as simple as unarchiving the binary distribution to a directory of your choice. In Chapter 2, you will see how easy it is to deploy an enterprise application to your working Geronimo server.


Chapter 2: Basic Geronimo Configuration

Overview

With the latest Geronimo version installed and running on your machine, you are ready to try basic configuration and to deploy an application on Geronimo. This chapter provides you with the fundamentals required.

Specifically, this chapter:

  • Shows step by step how to deploy an enterprise Java application on Geronimo. This application will have a very typical component composition: Java Server Pages (JSPs), servlets, and Enterprise JavaBeans (EJBs) on Geronimo.

  • Introduces the basic use of the versatile deployer tool and demonstrates how it will be very useful for daily operation of a Geronimo server.

  • Demonstrates the use of the Web console for deploying applications and monitoring the state of running applications.

  • Describes the types of application and application components that can be deployed on Geronimo.

  • Illustrates Geronimo’s basic component lifecycle model and shows how this relates to the deployment of applications.

  • Discusses both the Java 2 Enterprise Edition (J2EE) specific and vendor-specific plans that are used in Geronimo.

  • Reveals how Geronimo persists deployed applications plus configuration between server restarts and discusses the composition of the Geronimo repository.

  • Shows how to control the set of applications that will be started when Geronimo starts up and shows how to override component configuration attributes that are already persisted during deployment.

The discussion in this chapter enables you to deploy many enterprise applications to Geronimo with the least amount of customization. Meanwhile, the potential for customizing your application deployment is examined, and an overview of the procedures and configuration files involved is presented. This overview provides you with the background required to understand the detailed exploration that follows in the rest of the book.

By the end of this chapter, you will have an understanding of the different enterprise application components that can be deployed on Geronimo. You will know all the steps involved in deploying a typical enterprise application on the server. In addition, you should be comfortable with the myriad of deployment descriptor and plans that can be customized during Geronimo application deployment.


Deploying Your First Geronimo Application

To deploy your first Geronimo application, you will need the Enterprise Application Archive (EAR) file. This application is contained in progeron.ear. The application shows the names of the authors for this book. Download the EAR file for this chapter from the following URL:

www.wrox.com/WileyCDA/Section/id-105127.html

The progeron.ear is a standard J2EE EAR file. In fact, the same EAR file can be deployed on any J2EE 1.4–compatible server. With Geronimo, it is especially easy, since you will not need to create any additional Geronimo-specific deployment descriptors.

Important

Some seasoned J2EE administrator and deployers may challenge this simplicity, since EAR files in many production scenarios will require server-specific plans to be deployed successfully. If you fall into this category, please bear with us - the later chapters will fully explore Geronimo-specific deployment plans.

An EAR file is a deployable unit that can contain other archives file and Web components. In the case of progeron.ear, it contains the following:

  • A JSP template, called authors.jsp, used to present the list of authors

  • A ControllerServlet that coordinates the flow of requests, talks with the back-end EJB, and sends data to the JSP for presentation

  • A stateless session EJB, called Authors, that contains the author name data to be displayed

Figure 2-1 illustrates the operations of the progeron application.

Image from book
Figure 2-1: The operations of the progeron application

In Figure 2-1, the EJB that contains the author names data is called Authors.EJB. There is also a JSP, called authors.jsp, that displays the table of authors. The ControllerServlet is the mediator. It accepts incoming requests, accesses the EJB for author information, and then forwards this information to the JSP for presentation to the user.

This EAR file is representative of a typical deployable enterprise application, with a variety of Web components inside the archive - including an EJB, a servlet, and JSP.

You can deploy this application on your Geronimo server in three different ways:

  1. Use the deployer command-line tool to deploy the EAR

  2. Use the Web console GUI to deploy the EAR

  3. Use Geronimo’s hot deployer to automatically deploy applications

This chapter provides coverage of 1 and 2. The hot deployer, while very easy to use, is typically used only by developers. In concept, any deployable archive you placed into the deploy subdirectory will be picked up by the hot deployer and deployed to the server. Chapter 6 provides detailed coverage of the hot deployer and its configuration.

Deploying Applications with the Geronimo Deployer Tool

You can use the deployer tool to deploy the application. The deployer can be found in the bin directory of your Geronimo distribution. There is a deploy.bat (or deploy.sh for Linux) that can be used immediately. For convenience, you should add the bin directory to your PATH environment variable.

The command to deploy the progeron.ear application is:

deploy deploy progeron.ear

Of course, this assumes that progeron.ear is in the current directory. Otherwise, just enter the entire path to the EAR file as the last parameter. The first deploy in the previous line calls up the run-time-deployer via the deploy.bat (or deploy.sh) script; the second deploy specifies the deployment action to the run-time-deployer. When you enter this command, the deployer tool asks you for a username and password. Use the administrator username and password that you have entered during setup. If you have not changed it, the following default is available:

user name:      system
password:       manager

If your deployment is successful, you should see output similar to the following:

>deploy deploy progeron.ear
Username: system
Password:

Password:

    Deployed default/progeron/11552985600093/car

      `-> progeron.war @ http://myhostname:8080/progeron

      `-> progeron-ejbs.jar

The deployer tool has just successfully deployed the progeron.ear file. The previous output provides the information shown in Table 2-1.

Table 2-1: Deployment Information Provided by the Deployer Tool Open table as spreadsheet
Deployment Information | Description
Deployed default/progeron/11552985600093/car | The module (EAR file) that has been deployed. A default module ID is generated by Geronimo.
progeron.war @ http://myhostname: 8080/progeron | The Web module (WAR file) that has been deployed to the Web application server, and the context root path at which this module has been deployed. In this case, conforming to standard J2EE requirement, the Web module (progeron.war) is actually contained within the EAR file (progeron.ear).
progeron-ejbs.jar | The EJB tier archive (JAR file) that has been deployed to the EJB server.

Figure 2-2 reveals the archive file bundling inside progeron.ear.

Image from book
Figure 2-2: Inside the progeron.ear file

In Figure 2-2, you can see that both progeron.war and progeron-ejbs.jar are archived together within the progeron.ear file. In addition, a standard J2EE deployment descriptor for an enterprise application (called application.xml) is included. The following is the content of 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>progeron-ejbs.jar</ejb>
    </module>
    <module>
        <web>
            <web-uri>progeron.war</web-uri>
            <context-root>/ProGeronimo</context-root>
        </web>
    </module>
</application>

This application.xml descriptor basically tells the server about the deployable units that are in the archive. Each one of the deployable units is destined for a different server inside Geronimo. Figure 2-3 illustrates how the two deployable units inside progeron.ear are deployed to the servers inside Geronimo.

Image from book
Figure 2-3: Components inside progeron.ear are deployed to different servers

In Figure 2-3, the Web-tier components (such as JSP and servlets) are bundled inside progeron.war and are deployed to the Web-tier server in Geronimo. This server is either Jetty or Tomcat, depending on whether you have downloaded and installed the Jetty or Tomcat version of Geronimo. The context root at which the application is deployed is dependent on the <context-root> element in application.xml.

In this case, it is deployed at the context /ProGeronimo. The context root is the part of the URL used to access this application on the server. The following URL shows the context root portion highlighted:

http://localhost:8080/ProGeronimo/authors.cgi

The progeron-ejbs.jar is an archive of the EJBs for the application. It contains the stateless session EJB called Authors. Geronimo will deploy this archive of EJB to the OpenEJB server. The OpenEJB server is a container for EJBs, compatible with the latest EJB 2.1 standard.

Now that you know how to deploy an application to Geronimo from a command line, the next section will show you an even easier way - deployment via the graphical Web console.

Application Deployment Using the Geronimo Web Console

The Web console is a Web application itself, written as a set of servlets and JSPs. The default installation of Geronimo has the console already integrated.

With the Geronimo server running, all you need to do is to run the Web console is to access the following URL:

http://localhost:8080/console/

You will be greeted with the console’s login screen, shown in Figure 2-4.

Image from book
Figure 2-4: Geronimo Web console login page

Enter the username and password that you have configured during setup, or use the default system-manager pair.

To see all the applications that are running on your server, look at the left panel for Application EARs, under the Application heading. Click on that. You should then see the right-hand side panel displaying the EARs portlet.

Important

A portlet is a developer’s term for a flexible GUI software component that can be used to compose a visual page displaying some application-specific information or a complete user interface. To us, it is simply whatever is displayed on the right-hand side of the browser screen.

Figure 2-5 shows the display of the portlet, listing the deployed progeron EAR.

Image from book
Figure 2-5: The progeron.ear application deployed and running on Geronimo

In Figure 2-5, you can see three deployed application EARs - two running and one stopped. The running ones include the Web console application itself and also the progeron application; the Tomcat version of the UDDI (Universal Description, Discovery and Integration) server is also installed, but not started.

Before you can try and deploy the progeron application EAR again using the Web console, you must first uninstall it from the server. Geronimo remembers all the applications that are deployed to it, so you will still see the progeron application running even if you shut down and restart the server. To uninstall the progeron application, and reinstall it using the Web console, perform the following steps in sequence:

  1. In the Application EARs portlet, click on the Uninstall command link next to the default/progeron/11552985600093/car modules. This will stop the running application and then uninstall it from the server.

  2. Once the application has been successfully uninstalled, you should see it removed from the list of running Application EARs.

  3. Click on the Deploy New menu selection on the left-hand side of the page. You will see the Install New Applications portlet in the right-hand pane, as shown in Figure 2-6.

    Image from book
    Figure 2-6: Installing the progeron.ear application via the Web console

  4. Click on the Browse... button, and select the progeron.ear, then click the Install button. Leaving the Start app after install checkbox checked.

This will deploy and start the application. You can click the Application EARs menu item on the left panel again and see that the application is now running (see Figure 2-7).

Image from book
Figure 2-7: Confirming the installation and running of Application EARs

You can deploy applications to Geronimo via the command-line deployer or GUI-based Web console - it is your choice. The end result is the same. To confirm that the application is indeed running, you can access it using the following URL:

http://localhost:8080/ProGeronimo/authors.cgi

You will then see the list of authors from this book. The names are actually managed by the stateless session EJB. The servlets access the EJB to obtain the data, then pass it to the JSP for generating the displayed page.

Using the procedures detailed earlier, you can deploy a variety of J2EE application components to Geronimo. The next section details the possibilities.


Geronimo and J2EE Software Components

Being a server that implements the complete J2EE 1.4 specification, Geronimo can run and manage a variety of different J2EE application components. All J2EE applications are composed of distinct software components.

In general, these applications or software components are bundled up in archive files (typically using a JAR-type utility), together with the appropriate required J2EE deployment descriptor (XML files).

The J2EE 1.4 software components that can be deployed to and executed on Geronimo include the following:

  • Java Server Pages (JSP)

  • Servlets and support Java classes

  • EJBs of all varieties, including stateless sessionless beans, entity beans, Bean Managed Persistence (BMP), Container Managed Persistence (CMP and CMP2)

  • Message Driven Beans (MDBs)

  • JCA-compliant connectors, including JDBC connectors to relational database management systems (RDBMSs), and JMS connectors to message queue (MQ) servers

Table 2-2 shows these application components and the associated deployment packaging.

Table 2-2: Geronimo Application Components and Associated Deployment Packaging Open table as spreadsheet
Application Component | Deployment Packaging
JSP | Part of a WAR (Web application archive) file
Servlets | Part of a WAR file
EJB | Either as standalone grouping in an EJB JAR file, or as part of an EAR (enterprise application archive)
MDB | Same packaging alternatives (as the previous EJB)
JCA | connectors In a RAR (resource archive) file

Before application components can be deployed to Geronimo, they must be packaged into standard archives and must include standard deployment descriptors as described in the next section.

Standard Deployment Descriptors

Deployment descriptors are XML files that contain information regarding the software component being deployed. There are generally two types of deployment descriptors:

  • Standard J2EE deployment descriptors

  • Geronimo-specific (vendor-specific) deployment descriptors

In the progeron.ear deployment example, you have only used the standard J2EE deployment descriptors. This is because Geronimo is designed to be able to deploy many J2EE applications without the need for vendor-specific deployment descriptors. This is a great feature, because it means that you can deploy the same EAR bundle to any compatible server (or even different versions of the same server) without having to create vendor-specific plans.

Important

The terms deployment descriptor and deployment plans are used interchangeably throughout this book. You will tend to see the use of deployment descriptors in referring to J2EE standard plans, while the use of deployment plan is more appropriate for vendor-specific plans.

Table 2-3 enumerates the standard J2EE deployment descriptors required in the respective archive files.

Table 2-3: Standard Deployment Descriptors Open table as spreadsheet
Packaging Archive File | Standard Deployment Descriptor
WAR file | A web.xml file in the WEB-INF subdirectory
EAR file | application.xml in the META-INF directory
EJB JAR file | ejb-jar.xml in the META-INF directory of the JAR file
RAR file | ra.xml in the META-INF directory

Most likely, you will be configuring and deploying WAR and EAR files regularly. These are the typical distribution unit output from development teams. Every change of application-level code by the development team will involve the construction of a new WAR or EAR archive.

You use a standalone EJB JAR archive when EJBs are deployed in isolation and not as a part of a bigger enterprise application. This may occur, for example, if you are deploying EJBs for access by multiple Web-tier WARs or directly by EJB client applications. However, you will almost always find EJB JAR files as part of an EAR archive.

RARs are connectors that are typically supplied by enterprise information system (EIS) server vendor. For example, a JDBC connector is supplied by the RDBMS vendor. Resources in RAR files seldom change. Because of this, the deployment of RARs will typically be infrequent.

Important

This brings up one interesting behavior of the Geronimo server. Applications or components deployed to Geronimo are persistent. That is, once you have deployed it, Geronimo will remember it. Even if the server is rebooted, the deployed application is still kept by Geronimo and the server will attempt to restart the application or component the next time it restarts.

Given that components deployed to Geronimo are persistent, there is no need to redeploy a set of components (forming an application) once they are deployed. Typically, in a production situation, you will only need to redeploy an application when there is a new release of the application.

Geronimo-Specific Deployment Descriptors

Some of the Geronimo-specific deployment descriptors that you may use include descriptors that are often called deployment plans (see Table 2-4).

Table 2-4: Geronimo-Specific Deployment Plans Open table as spreadsheet
Package Archive File | Geronimo-Specific Deployment Plan
WAR | geronimo-web.xml under WEB-INF, alongside the required web.xml descriptor
EAR | geronimo-application.xml under META-INF, alongside the required application.xml descriptor
JAR | openejb-jar.xml under META-INF, alongside the required ejb-jar.xml descriptor
RAR | geronimo-ra.xml under META-INF alongside the ra.xml descriptor

These Geronimo-specific deployment plans are not always required. They provide additional deployment control and application run-time configuration above and beyond those offered by standard J2EE descriptors. Chapters 9 to Chapter 15 will provide more details on these plans. For now, it is sufficient to know you may need one of more of them when you deploy your applications in production.

In addition to server-side support, Geronimo also provides J2EE client support. J2EE client code can be bundled in client JAR file and deployed with Geronimo as a client container. The Geronimo-specific deployment plan in this case is called geronimo-client.xml and should be placed in the META-INF directory of the JAR archive containing the J2EE client code. J2EE client support in Geronimo 1.1 is limited, since the client using this support is restricted to running on the same host as the server itself. This limitation is expected to be lifted in a future release.

External Deployment Plan

To be totally flexible with deployment, Geronimo will accept a deployment plan that is specified during the deployment process. This means that the Geronimo-specific deployment plan need not be bundled in as part of the archive. This makes it possible to create a generic EAR file that can be deployed on multiple J2EE servers and add the Geronimo-specific details at deploy time.


Loading, Starting, and Stopping Components

When running inside the Geronimo server, a software component often makes reference to another software component. For example, a servlet may make a call to a session EJB. The servlet in this case depends on the EJB to work properly. This creates a dependency between the two components. As the server container, it is Geronimo’s job to ensure that component dependencies are satisfied when the application runs.

Important

A component in Geronimo is actually called a GBean, which is short for Geronimo-Bean. A Geronimo server is internally composed of a collection of GBeans.

The process of deploying an application component to Geronimo can be broken down into the following sequence of events:

  1. Geronimo examines the archive for deployment descriptors and deployment plans. Geronimo configures the components from the archive according to the instructions in the descriptors and the plans. This will also involve resolving any dependencies between the components. The saved configuration of components is called a module in Geronimo.

  2. The module, consisting of configured components, is saved in a repository maintained by Geronimo.

  3. Geronimo starts the components by loading the module from the repository, allowing the application to run and start the processing of incoming requests.

Step 1 is called the configuration or building phase. During this phase, Geronimo will load the components, resolve dependencies, and configure them. The configured components are then saved in a persistent form during Step 2. Doing things this way ensures that the components can be started very quickly later.

Step 2 is called the distribution phase. You have distributed an application if it has been copied by Geronimo into Geronimo’s own managed repository.

Important

As of release 1.1, Geronimo’s configuration store is physically a directory hierarchy. In fact, if you look under the repository directory in the location where you have installed Geronimo, you will see a bunch of directories and subdirectories with names corresponding to their module IDs.

Application modules are started during Step 3. This consists of loading the persisted, preconfigured components from the repository. The components in the started module are also initialized in this step.

At any time, an administrator (that’s you) may decide to stop a set of running components. This can be done by stopping the module. Stopped modules still have their image on disk (in the repository). However, stopped component cannot process incoming user requests.

Important

To keep component configuration as flexible a possible, Geronimo 1.1 has the ability to override certain configuration parameters during the loading of the persisted modules. This occurs as part of Step 3. The configuration parameters that are changed are specified by an administrator in the var/config/config.xml file. The use of this file for configuration is covered in the section Making Basic Configuration Changes to Modules later in this chapter.

To completely remove an application from a Geronimo server, you must undeploy it (that is, uninstall it). Undeployment includes cleaning up the preloaded image of the application by removing it from the Geronimo-managed configuration store.

Geronimo comes preconfigured with certain modules already installed and running. You can see all the modules by using the following command:

deploy --user system --password manager list-module

The list you will see is similar to Figure 2-8.

Image from book
Figure 2-8: The list of modules currently deployed on the server

In Figure 2-8, all the configurations on the list have already been deployed to the server. They are persistent and can be restarted at any time. The configurations with a plus sign (+) in front of them are actually running on the server. The ones without the plus sign are deployed but not started. This means that they were not configured to start, that they were shut down previously, or that a failure condition has occurred and they are in a failed state.

For started applications, the URL to the root context of the application is also shown, after an @ sign. This URL can be used to access the component via a browser. For example, in Figure 2-8, the welcome page to Geronimo can be accessed by using http://your-e7423197eb:8080/.

The Geronimo Component Lifecycle

Figure 2-9 illustrates the lifecycle of a component in Geronimo.

Image from book
Figure 2-9: The lifecycle of a Geronimo-managed module

A module is loaded (but not started) when it is first read from the repository and loaded into memory. The module is in the loaded/stopped state at this time.

Once the module is successfully loaded (including configuration and preparation for any dependent components), it can be started. This puts it through the starting state. Once the component is started successfully, the component is in the running state. In the case of a Web application, the application is ready to accept incoming requests in the running state.

If starting is unsuccessful, the module falls into the failed state. The module remains loaded but is not running in the failed state. Modules in the failed state may be stopped, restarted, or undeployed (removed from the server’s repository).

The Geronimo server manages the lifecycle of its contained applications. Each application is deployed and controlled as a module.

Important

A module is Geronimo-specific terminology that refers to a tightly bound grouping of configured software components. One of the unique properties of the components within a module is that they have a common lifecycle. From the Geronimo server’s perspective, each and every deployed J2EE application is a separate and distinct module. Incidentally, this roughly corresponds to the J2EE concept of a deployable module.

A deployed module receives a signal to start or stop whenever the following occurs:

  • You, as an administrator, start or stop the application using the deployer tool, Web console, or Ant scripting.

  • Geronimo detects a dependency while starting or shutting down another dependent module.

  • The server itself is starting up or shutting down.

Table 2-5 summarizes the states in a Geronimo module’s lifecycle, as managed by Geronimo.

Table 2-5: Geronimo Module Lifecycle States Open table as spreadsheet
State | Description
Loaded | The module has been installed on the Geronimo server but has not yet been started.
Starting | The module is in the process of starting up. During this time, it performs initialization, allocates required resources, and prepares for operation. A module may fail to start if an exception condition occurs during this process.
Running | The module has started successfully and is operating in its normal state. Applications can run indefinitely in this state. Even when encountering abnormal conditions, most modules can deal with the situation and log the details. However, when the error condition is fatal, the application may enter the failed state.
Stopping | The module is in the process of stopping. This may involve the release of resources and notifying other dependent components.
Stopped | This is indistinguishable from the loaded state. The application enters this state when it has successfully completed the stopping state or when it was first installed.
Failed | The module has failed and stalled. This state can be entered at any time when an application is starting, stopping, or running.

You will see references to these states throughout this book and in Geronimo’s documentation. Thankfully, they are quite easy to conceptualize and understand.

Important

The industry-drafted Java Specification Request, JSR-88, details the states that deployed applications can be in within a J2EE container. Geronimo strictly follows this standard in its implementation.

Making Basic Configuration Changes to Modules

Some properties of the default Geronimo modules can be changed quite simply. If you look in the var/config directory, you will find the following file: config.xml. This file is vital to the operations of the Geronimo server. It serves two very important functions:

  • As a list of installed modules that will be (optionally) started when the server (re)starts

  • As a convenient way to override some basic configuration parameters of the modules before the server starts

The following examines each of two functions of config.xml.

The config.xml as a What to Start List

The config.xml file describes the modules that are installed on this server and can be optionally launched automatically when the Geronimo server is started. The order in which modules are listed in config.xml is the order in which they start when the server starts up.

If you examine the config.xml file, you will find a root <attributes> element with many <modules> subelements. Each <modules> subelement describes an installed module. An installed module is one that has been deployed to the server - configured and saved in the repository. A load attribute of the <module> element also controls whether the module will be started. If this attribute is set to load='false', the installed module will not be started.

Since you have already deployed the default/progeron/11552985600093/car module on the server, and this module will be restarted when the server starts, you will find an entry for default/progeron/11552985600093/car module in this file. It is the last entry, highlighted in the following abbreviated listing of config.xml.

<?xml version="1.0" encoding="UTF-8"?>

<attributes xmlns="http://geronimo.apache.org/xml/ns/attributes">
  <module name="geronimo/rmi-naming/1.1-SNAPSHOT/car">
    <gbean name="RMIRegistry">
      <attribute name="port">1099</attribute>
    </gbean>
    <gbean name="NamingProperties">
      <attribute name="namingProviderUrl">rmi://0.0.0.0:1099</attribute>
    </gbean>
  </module>
  ...
  <module name="default/progeron/11552985600093/car">
  </module>
</attributes>

</attributes>

This file is part of the persistence mechanism of Geronimo - how it remembers what to start between reboots. Each <module> entry represents an installed module and can optionally be started. All of these modules are system components that make up the J2EE 1.4 personality of the server.

Anytime you start an application EAR bundle on the server, you should see the module name added to this list. This means that your application is installed and will be started automatically the next time the server starts up.

Important

It is important to realize that the Geronimo server actually writes to this file during its operation. This is the only way that the configuration that you deploy can be added to the file automatically. Because of this, you must not modify this file while the Geronimo server is running. You can, however, safely edit this file after the server shuts down.

Reconfiguring GBean Components with config.xml

The second personality of config.xml enables you to make minor attribute changes to GBean components within a listed configuration. These attributes will affect how the component behaves the next time Geronimo starts. Recall that a module consists of a group of components (GBeans are software components in Geronimo) that have the same lifecycle.

Important

Modify config.xml with great care, since editing errors in this important file can cause the server to behave erratically, or not start at all.

Some of the modules listed in config.xml may contain GBeans that have configurable attributes. These attributes may already have configured values in the persisted module image in the repository. However, if you make modifications to these attribute values in config.xml, the preconfigured value is overridden when the modules is started by the Geronimo server.

The following is the content of the default config.xml file (with the default/progeron/11552985600093/car module added at the end):

<?xml version="1.0" encoding="UTF-8"?>

<attributes xmlns="http://geronimo.apache.org/xml/ns/attributes">
  <module name="geronimo/rmi-naming/1.1/car">
    <gbean name="RMIRegistry">
      <attribute name="port">1099</attribute>
    </gbean>
    <gbean name="NamingProperties">
      <attribute name="namingProviderUrl">rmi://0.0.0.0:1099</attribute>
    </gbean>
  </module>
  <module name="geronimo/j2ee-server/1.1/car">
  </module>
  <module name="geronimo/j2ee-security/1.1/car">
    <gbean name="geronimo.remoting:target=JaasLoginServiceRemotingServer">
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">4242</attribute>
    </gbean>
    <gbean name="JMXService">
      <attribute name="protocol">rmi</attribute>
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">9999</attribute>
      <attribute name="urlPath">/jndi/rmi://0.0.0.0:1099/JMXConnector</attribute>
    </gbean>
  </module>
  <module name="geronimo/axis/1.1/car">
  </module>
  <module name="geronimo/openejb/1.1/car">
    <gbean name="EJBNetworkService">
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">4201</attribute>
    </gbean>
  </module>
  <module name="geronimo/j2ee-corba/1.1/car" load="false">
    <gbean name="NameServer">
      <attribute name="dbDir">var/cosnaming.db</attribute>
      <attribute name="port">1050</attribute>
    </gbean>
    <gbean name="Server">
      <attribute name="args">-ORBInitRef,
NameService=corbaloc::localhost:1050/NameService</attribute>
    </gbean>
    <gbean name="UnprotectedServer">
      <attribute name="args">-ORBInitRef,
NameService=corbaloc::localhost:1050/NameService</attribute>
    </gbean>
  </module>
  <module name="geronimo/system-database/1.1/car">
    <gbean name="DerbyNetwork">
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">1527</attribute>
    </gbean>
  </module>
  <module name="geronimo/activemq-broker/1.1/car">
    <gbean name="ActiveMQ.tcp.default">
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">61616</attribute>
    </gbean>
  </module>
  <module name="geronimo/activemq/1.1/car">
  </module>
  <module name="geronimo/directory/1.1/car" load="false">
    <gbean name="geronimo.server:name=DirectoryService">
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">1389</attribute>
    </gbean>
  </module>
  <module name="geronimo/ldap-realm/1.1/car" load="false">
  </module>
  <module name="geronimo/tomcat/1.1/car">
    <gbean name="TomcatResources">
    </gbean>
    <gbean name="TomcatWebConnector">
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">8080</attribute>
      <attribute name="redirectPort">8443</attribute>
    </gbean>
    <gbean name="TomcatAJPConnector">
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">8009</attribute>
      <attribute name="redirectPort">8443</attribute>
    </gbean>
    <gbean name="TomcatWebSSLConnector">
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">8443</attribute>
    </gbean>
    <gbean
name="geronimo/tomcat/1.1/car?ServiceModule=geronimo/tomcat/1.1/car,j2eeType=GBean,
name=TomcatWebContainer">
      <attribute name="catalinaHome">var/catalina</attribute>
    </gbean>
  </module>
  <module name="geronimo/geronimo-gbean-deployer/1.1/car">
  </module>
  <module name="geronimo/j2ee-deployer/1.1/car">
    <gbean name="WebBuilder">
      <attribute
name="defaultNamespace">http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-
1.1</attribute>
    </gbean>
  </module>
  <module name="geronimo/openejb-deployer/1.1/car">
    <gbean name="EJBBuilder">
      <attribute name="listener">?name=TomcatWebContainer</attribute>
    </gbean>
  </module>
  <module name="geronimo/client-deployer/1.1/car">
  </module>
  <module name="geronimo/axis-deployer/1.1/car">
  </module>
  <module name="geronimo/javamail/1.1/car" load="false">
    <gbean name="SMTPTransport">
      <attribute name="host">localhost</attribute>
      <attribute name="port">25</attribute>
    </gbean>
  </module>
  <module name="geronimo/sharedlib/1.1/car">
    <gbean name="SharedLib">
      <attribute name="classesDirs">var/shared/classes</attribute>
      <attribute name="libDirs">var/shared/lib</attribute>
    </gbean>
  </module>
  <module name="geronimo/tomcat-deployer/1.1/car">
  </module>
  <module name="geronimo/welcome-tomcat/1.1/car">
  </module>
  <module name="geronimo/ldap-demo-tomcat/1.1/car" load="false">
  </module>
  <module name="geronimo/servlets-examples-tomcat/1.1/car" load="false">
  </module>
  <module name="geronimo/jsp-examples-tomcat/1.1/car" load="false">
  </module>
  <module name="geronimo/webconsole-tomcat/1.1/car">
  </module>
  <module name="geronimo/uddi-tomcat/1.1/car" load="false">
  </module>
  <module name="geronimo/daytrader-derby-tomcat/1.1/car" load="false">
  </module>
  <module name="geronimo/remote-deploy-tomcat/1.1/car">
  </module>
  <module name="geronimo/hot-deployer/1.1/car">
  </module>
  <module name="default/progeron/11552985600093/car">
  </module>
</attributes>

Changing the Port and IP Address of Service Listeners

The most useful (and frequently changed) parameters are highlighted in the preceding listing. They typically represent the host adapter IP address and port number that each system service will listen for request on. The IP address 0.0.0.0 is special in that it tells the server to listen for requests on all hardware adapters. Many server machines may have two or more hardware network adapters (connecting to multiple networks at the same time-called multi-homed). Using an IP address other than 0.0.0.0 will allow you to specify the network adapter that the service should listen on for requests.

For example, as shown in config.xml, the TomcatWebConnector GBean component is configured to listen, by default, on all adapters, port 8080. Say that you change the highlighted configuration lines to the following:

<gbean name="TomcatWebConnector">
  <attribute name="host">198.0.0.1</attribute>
  <attribute name="port">8081</attribute>
  <attribute name="redirectPort">8443</attribute>
</gbean>

This will cause the Jetty Tomcat connector to listen to incoming HTTP requests exclusively on the network adapter with IP address 198.0.0.1 and on port 8081. This new configuration will take effect the next time Geronimo starts up.

Another way to modify the basic configuration is by using the Web console. The Web console allows you to modify component configuration simply by changing some values using a GUI.

Note that, in order to use config.xml to modify the attributes of the GBean components, you must somehow know the available GBean names and attributes to modify. You can discover these components and attributes name via one or more of the following:

  • Their existence in the config.xml file

  • From the component’s documentation (for example, documentation for the Tomcat AJP connector GBean)

  • From their configuration description in this book

  • From the actual components’ deployment plan in Geronimo’s source code

In practice, there are only a limited number of GBeans and attributes of interest to administrators. Most of these configuration attributes will be covered in this book. There should be little need to actually examine the source code deployment plans.

In fact, Geronimo’s designers have ensured that the most commonly configurable GBeans and attributes have a GUI created for them - in the Geronimo Web console. You can configure these GBeans and attributes using the GUI without actually knowing the GBean and Attribute names. This is explored further in the next section.

Important-Assembly-Time versus Run-Time Configurability

By design, the components that make up a Geronimo server are highly configurable. Having adaptive and highly configurable components is a cornerstone of modern, reusable, modular software design. A constant struggle, however, at Geronimo design meetings, is determining how much of this configurability should be passed on to the administrator at deploy time. On one hand, the pro dynamic configuration pundits are insisting that tens or even hundreds of configuration parameters per component be passed to run time (when the Geronimo server starts or restarts). This enables the ultimate dynamic configurability. This, of course, will increase the configuration complexity for administrators and beginning users. And, when you figure that Geronimo starts up with at least a dozen or so modules, this complexity can escalate quickly. In addition to configuration complexity, providing too many configurable parameters also dramatically increases the possibility of erroneous configuration - resulting in a server that cannot be started or is started in a corrupted state. This affects the observed stability of the overall system. With this in mind, the designers of Geronimo make a lot of configuration choices at assembly time, leaving only a manageable number in the config.xml file. Assembly time refers to the time when the server personality is built into your binary distribution. There are many different ways of assembling the components to create different servers; the J2EE server is one of these possibilities. The Little-G minimal server, for example, is another assembly where the goal is to create the smallest functional server possible.

Modifying Configuration Attributes Using the Web Console

Many of the attributes that are contained in the config.xml file can also be changed safely through the Web console. For example, examine how you would change the IP address and port number that the Tomcat Web Connector will listen to.

This can be accomplished in the Web console by:

  • Clicking on the Web Server menu item on the left

  • Clicking on the edit action of the TomcatWebConnector component in the Network Listener portlet in the right-hand pane

You should see the configurable attributes for this listener component, as shown in Figure 2-10.

Image from book
Figure 2-10: Configurable attributes for TomcatWebConnector listener component

Modifying the values on the portlet shown in Figure 2-10 and clicking Save will write them to the config.xml file. These changes will take effect the next time Geronimo is started.

Important

Some readers may notice that there is an additional attribute called max threads that is not included in the original config.xml file. This attribute is configurable via config.xml, but since its value is not modified there, it will take on the predefined default values.


Summary

In this chapter, you have successfully deployed a full-fledged enterprise application to the Geronimo server. Applications can be deployed to Geronimo using either the command-line deployer tool or the Geronimo Web console GUI.

Enterprise applications bundled in EAR file, Web applications bundled in WAR files, EJBs bundled in JAR files, or JCA connectors bundled in RAR file can all be readily deployed to Geronimo.

Deployment descriptors are XML files used during deployment to give the server information and configuration hints for the components being deployed. Standard J2EE deployment descriptors are specific in their names and location. A deployment bundle having only J2EE deployment descriptors can be deployed on any compliant server. Geronimo is designed to be able to work with these bundles as much as possible. In some production cases, however, you may have to add Geronimo-specific deployment descriptors (called deployment plans).

Geronimo deployment plans can either be included as part of the archived bundle or supplied during deployment. Supplying a plan during deployment potentially enables the same application bundle to be deployed in different ways.

As part of deploying an application, you have the option of starting it. Configured and deployed applications are referred to as modules in Geronimo. In general, deployed modules can have their lifecycle controlled and managed by Geronimo. The available states that a component can be in are started, stopped, or failed. Deployed components are persistent between restarts of the server. This means that once you have deployed an application, you will not need to redeploy it unless there are code changes.

Deployed modules are maintained in the repository by Geronimo. The repository is a directory hierarchy. The code and configuration files of a module can be located within this hierarchy under directories matching its module ID. Configuration information is maintained in serialized format in the same directory for optimized loading.

The config.xml file contains descriptions of the modules that are installed and can be used to control those that will be started up when a Geronimo server restarts. It is part of the mechanism that Geronimo used to persist module startup information. You can also override certain attributes of the GBean components in a module by editing the config.xml file. This latter feature is useful for customization of hostname and TCP/IP port for Web-tier services.

In Chapter 3, you will discover some background of Geronimo and the people behind this modern classic Open Source server project.


Chapter 3: Apache and Geronimo

This chapter takes a mini-break from hands-on working with Geronimo to take a look at something that is very important to many Geronimo users. This chapter traces the origin of the Geronimo project. It focuses on the people who are behind the versatile server and the organizations that are backing these people. For readers who may not be interested in this background and history, feel free to skip forward a chapter, because this chapter contains no technical content.

The discussion in this chapter helps to answer the age-old question of how Open Source software works. The chapter also looks at the various widely adopted Open Source licenses, examines their terms, and explains how they may affect you as a user.

More and more organizations are adopting Open Source software for their production projects. This is certainly true if you are already exploring the use of Geronimo in your enterprise. The chapter shows some of the real benefits that Open Source software can bring to the table, and it also points out some pitfalls.

By the end of this chapter, you will have an appreciation for the history of Geronimo. You will become familiar with the developer community that created Geronimo, as well as the organization that is hosting the project. You will also be able to discern the differences between the different Open Source software licenses available and understand why the Apache 2.0 license is most appropriate for the Geronimo project. Last, but certainly not least, you will understand how adopting Open Source software (such as Geronimo) can provide tangible long-term benefits for your development project, and maybe even your company.

The Organization behind Geronimo

Geronimo is a very large Open Source software project, with developers from all over the world. They share the development and maintenance of the server code by working on a common source code repository. Work proceeds around the clock, since contributors are located in different time zones and have differing availability throughout the day. This shared repository is located on servers hosted by the Apache Software Foundation.

The Apache Software Foundation (ASF) is a nonprofit organization created to foster the growth and prosperity of Open Source software communities, leading to the creation of world-class Open Source software projects. The ASF has a rather interesting history dating back to the mid-1990s. It originated around one of the world’s most successful Open Source products.

Founded on World’s Most Popular Web Server

The spirit of the Apache Software Foundation, as its name implies, has its origin in a collaboration and administration model that evolved from the development of a very well known Web server - the Apache Web server. Indisputably the world’s most popular Web server, the Apache Web server had a very humble beginning.

The code that forms today’s Apache Web server originated from early public domain source code from National Center for Supercomputing Applications (NCSA) at the University of Illinois, Urbana-Champaign. The core code was well written for the time, but once the author, Rob McCool, left the NCSA in 1994, there was no official support for the public domain code.

Meanwhile, a group of Web masters from all over the world used the NCSA code and gathered together to collaborate on fixing defects and providing enhancements to the code base. Using emailed code patches as the main mechanism, the group shared user information and administrative tips, as well as code changes and enhancement. The Apache Group was formed in February 1995. The name Apache springs from the fact that the vulnerable server code is similar to a big patch-”A ‘Patch’y.” (For an interesting exploration, see the FAQ at http://httpd.apache.org/docs/1.3/misc/FAQ.html#name.)

The group continued to expand and pick up new contributors throughout the year, leading to the release 1.0 of the Apache Web server in December of 1995. Because of the strong community of Web masters (users of the Web server) behind the project, the Apache Web server adoption exceeded its NCSA parent within a year of release 1.0. The rest is history.

Based on a survey by Netcraft (http://news.netcraft.com/archives/web_server_survey.html, which is an industry-accepted statistics source, as of August 2006, the Apache Web server commanded the lion’s share of users on the Internet - a whopping 62 percent of the market share (representing more than 57 million servers. The next closest competitor is Microsoft Internet Information Server (IIS), weighing in at a distant 30 percent market share.

This installed user base proves that an online user and developer community centered around Open Source code can provide the support and development resources required to make a world-class project. The Apache Group (the name the team took on) is the first Open Source group in history to demonstrate this viability and to take the majority market share in a highly competitive market.

Apache Software Foundation

The Apache Group reorganized to form the Apache Software Foundation (ASF) in 1999. This was necessary because, as the membership in the original group grew, the formal administration, legal, and financial issues needed to be dealt with effectively.

At the same time, the ASF has created a reusable cyber-infrastructure for the bootstrapping, launching, promoting, and sustaining of Open Source projects. With time, this value is realized by the greater Open Source community - resulting in a large spread of projects being managed under the ASF.

Today, a very large number of successful Open Source projects have flourished under the ASF’s auspices. You can get a feel for the breadth of the projects by visiting the ASF official site, at www.apache.org. Figure 3-1 shows a recent front page from the ASF site.

Image from book
Figure 3-1: Homepage of the Apache Software Foundation

In Figure 3-1, you can see the large number of projects on the left panel. These are called top-level Apache projects and are explained later in this chapter.

Also interesting is how the ASF is funded. Other than private donations, the Web site in Figure 3-1 shows some innovative ways that you can contribute to the foundation. It is important to point out that, while the ASF brings together developers and users around software projects by providing the computing resources needed for collaborative development and communications, it does not fund the software projects itself. In fact, most Open Source software developers donate their time and effort on the project. Like the Web masters who started the original Apache Web server project, these individual developers and contributors stand to gain from the high-quality final products that the collaborative process generates. They typically are also long-term users of the products.

Geronimo Has Inherited the Apache Spirit

Completely consistent with the founding spirit, the Geronimo project feeds off a thriving community. It is a global community of Java 2 Enterprise Edition (J2EE) users and developers. The community members interact via the ASF-hosted Web site, together with a wide variety of alternate supporting communications channels - including mailing lists, issue-tracking systems, wiki, and direct email.

The Geronimo server’s code base is the focus of the community. Any member of the community is welcomed and encouraged to do the following:

  • Use the software

  • Ask for help on any of the community communication channels

  • Report defects

  • Make suggestions for future enhancement

  • Participate in technical design discussions

  • Provide assistance to other new users

  • Submit code patches to fix defects and/or add features

  • Contribute existing code (possibly from commercial products) that would be useful for the project, which must be approved by the overseeing Project Management Council (PMC)

While the project management committee has the final vote and say on administrative and technical decisions, the consensus-based decision-making process is formally documented by the ASF and followed religiously. The wider community’s input is also regularly solicited through the communication channels and considered heavily when making decisions.

Without the initial group of enthusiastic Web masters, the Apache Web server would have never reach its de facto status today. Without a large group of enthusiastic J2EE server users and developers, Geronimo cannot reach its fullest potential. The PMC and the committers both realize this and do their best to ensure the growth and prosperity of the community.

Geronimo As a Top-Level ASF Project

Figure 3-2 shows the organization of software projects on the ASF.

Image from book
Figure 3-2: Organization of projects at the Apache Software Foundation

The projects at the ASF are organized into two levels, as shown in Figure 3-2. Top-level projects are either of the following:

  • Major, matured, well-known projects in their own right

  • A grouping of second-level projects or subprojects

For example, the Jakarta project consists of many Java-based technology projects (not all projects in the ASF are written in the Java programming language). This includes the Velocity project among others. The Web services top-level project in Figure 3-2 houses many subprojects, including Axis, and Scout, to name just two.

When there is enough support and demand for a particular second-level project, it may be promoted to the top level. For example, Ant was formerly a subproject. Geronimo started life as a project under the Incubator. The Incubator is where projects and communities new to the ASF are bootstrapped. The next section provides a cradle-to-present timeline of the Geronimo project.

The Geronimo Project Timeline

Started in August 2003, the Geronimo team completed a J2EE 1.4–compatible server from scratch in about two-and-a-half years. Figure 3-3 shows a historical timeline of the Geronimo project that notes some interesting events.

Image from book
Figure 3-3: Historical timeline of major events associated with the Geronimo project

The significant events, from its conception to the time of this book’s publishing, are shown in Table 3-1. You can cross-reference the rows in Table 3-1 with the timeline in Figure 3-3.

Table 3-1: Significant Events on the Geronimo Project Timeline
Open table as spreadsheet

Date

Description

June 2003

A group of developers walked out of their involvement in the JBoss project and formed their own business. The resulting company was called Core Developers Network, and the idea was to obtain Open Source consulting, training, and support work to fund and sustain the group’s Open Source work. They strived to create a J2EE container from scratch, leveraging their accumulated experience and expertise. These developers, and others that followed, were to become the founding members of the Geronimo project.

August 2003

Accepted as a participant in Sun’s certification efforts, the ASF announced their intention to create a new software project around a community of J2EE users and developers. This was a perfect project for the members of the Core Developers Network.

The Geronimo project began in the Apache Incubator. The Incubator is an isolation chamber for startup projects. It is a place within the Apache organization where beginning projects and the developers behind them can benefit from the resources provided by the ASF while learning the ropes of the Apache Way. Some incubated projects, unfortunately, never make the cut. The Geronimo project started in the Incubator in August 2003. In this particular case, the incubation was mainly for the training and establishment of a PMC to govern the large Geronimo project.

November 2003

A demonstration at ApacheCon 2003 showed Geronimo running the de facto server benchmark of the time - Java Pet Store - for the first time. The Geronimo developers spent weeks of sleepless nights to prepare this operational demo, delivered during the conference from the Las Vegas conference hotel bar.

February 2004

By February of 2004, the Geronimo project and its new PMC graduated to a top-level project status at the ASF. Work continued in earnest throughout the year of 2004 to build the J2EE server.

April 2004

Geronimo 1.0 Milestone 1 debuts, providing a base set of functionality in an effort to gather initial feedback to continue forward.

September 2004

In September 2004, Geronimo 1.0 Milestone 2 was released. This was largely a demonstration-of-capabilities release, featuring partial support for Web applications and Enterprise JavaBean (EJB) deployments (for example, EJB CMP was not fully implemented).

November 2004

The Milestone 2 release was followed by a more full-featured Milestone 3 release in November 2004. Unfortunately, the configuration and deployment mechanism for EJB was broken in this release. Most evaluation users who needed to work with EJBs had no other choice but to download the latest unstable code from the code repository and build it themselves.

January 2005

In late 2004 and early 2005, a company named Gluecode Software, which was formally recognized for donating the Business Process Management (BPM) engine for Apache Agila, started to recruit key Geronimo developers, many from Core Developers Network. While commercial enterprise recruitment of developers from Open Source projects is certainly not new news, in almost all cases the new employment does not involve continual paid involvement in the Open Source project. Gluecode hired the Open Source developers, and all the developers continued their commitment to the Open Source Geronimo project.

In fact, Gluecode built its flagship product on top of Geronimo to make the business case. The Gluecode product was a rebundling of the pieces that composed the Geronimo project. This bundling was less ambitious in that it did not include the EJB container component of Geronimo. In addition, Gluecode added to the mix its own GUI-based Web console for configuration and management (this was later donated to the project) and the integration of the Apache Pluto portlet engine. This allowed Gluecode to build on top of the Geronimo infrastructure to catapult the development of its commercial product.

This marked one of the first publicly visible hiring and continued support of Open Source developers. It was a sign of the times. High-quality, robust Open Source software often involves world-class software engineering that is on par with (or superior to) any creations originating from any proprietary software vendor. Yet, the Open Source developers are often required to work at night and on their own time - skirting around the mundane (but bill-paying) activity they grudgingly called the day-job.

May 2005

IBM announced its acquisition of Gluecode. This meant that several key Geronimo developers immediately became IBM employees.

While the community was skeptical in the beginning, it soon became clear that IBM intended for Gluecode to continue its intense contribution to Geronimo. IBM also started to market support services for users of the Geronimo server. IBM also continued to market the Gluecode product - a product built on top of Geronimo.

Later in the year, IBM announced its Community Edition of the Websphere Application Server, based entirely on Geronimo.

August 2005

It was a long wait for many early adopters, but Milestone 4 finally arrived in August 2005. Milestone 4 is often described as the full-featured release prior to certification. This milestone release fully supported the deployment of Web-tier components, EJBs, enterprise applications, and Message Driven Beans (MDBs). For users evaluating Geronimo, this was the release that they had been waiting for - since almost all of the planned features were in place and functional. Jetty is the primary Web-tier container in this release. While Tomcat is integrated, it requires some major surgery on the configuration files and a rebuild to activate it.

October 2005

In early 2005, with most of the planned features in place, the team focused its work on getting the details right and on J2EE certification. The certification effort was both tedious and time-consuming. The work cumulated in the very first milestone release that was officially J2EE 1.4–compatible -Milestone 5 in October 2005. Milestone 5 also included the capability to easily switch between Jetty and Tomcat as the Web container, without rebuilding.

January 2006

With release 1.0, the future was met with a certified version of Geronimo. The announcement of Geronimo 1.0 at ApacheCon 2005 in San Diego (December 2005) was the moment that the entire Geronimo team had been working toward. The actual server code was not ready until early January of 2006, leading to a few weeks of anxiety among excited new users.

June 2006

Release 1.1, a robust bug fix release of Geronimo, is announced around the time of the JavaOne annual Java developer conference - May 2006. This release contains major bug fixes, a new syntax for specifying component modules, as well as new features such as support for hot deployment, support for Geronimo plug-ins, and a GUI-based installer. The actual distribution of Geronimo 1.1 was made available late June 2006.

At release 1.1, Geronimo gathered a significant community of J2EE users and developers. Moving forward, this community is likely to continue its growth. If the original Apache Web server is any guide, the ultimate community size and user base can be quite significant.

It is certainly an opportune time for users of proprietary J2EE servers to consider migration to Open Source. Often, however, a user coming from a commercial J2EE environment is full of doubt and questions about Open Source in general. The next section addresses these concerns.

Benefits of Open Source Software

There are many known and proven benefits in adopting Open Source software. Some of these benefits are quite tangible, while others are more abstract. Among the concrete benefits are:

  • The software itself is typically free of charge, even when deployed for commercial purposes.

  • Since the source code is available, you can always modify it if you need to adapt it to specific needs (of course, this is subject to the software license).

  • Since the source code is available, you can fix the defects yourself and do not have to depend on a vendor’s schedule.

  • Information, documentation (such as books and articles), and training are typically widely available from multiple sources, often internationally.

  • The number of consultants or developers with expertise on an Open Source software code base can be sizable, and, therefore, skilled labor on the code base is often more widely available than for proprietary software.

  • Wide availability of the source code typically means that support services from third parties are multisourced and competitive.

  • If you are working in a multinational company, you are not restricted by the countries in which the software vendor decides to do business. There are no geographic boundaries with freely distributed Open Source software.

  • You are protected from the risk associated with a proprietary software vendor going out of business, or a decision from the vendor to discontinue the product.

Some of the less tangible benefits include:

  • You benefit from the experience of other users like yourself. The contribution of ideas and fixes for defects from a large user community helps refine the definition and evolution of the software in a manner that is not possible to achieve within a proprietary vendor’s limited market.

  • Designers and developers on the job are fully qualified (in the case of the ASF, this status is achieved through a meritocracy - see the sidebar About the Geronimo Meritocracy) and typically highly experienced in the specific area. They typically work in collaboration to create the software. In many cases, you are getting the global-cream-of-the-crop developers working for you on an Open Source project.

  • Open Source projects tend to leverage and build upon other Open Source projects. This often means significant features and flexibility that often are not available in a proprietary vendor solution.

With all of these (very significant) benefits in mind, it is hard to see why someone would shy away from adopting Open Source software.

Important-About the Geronimo Meritocracy

Developers of projects at the ASF follow the rule of a meritocracy, inherited from the group that developed the Apache Web server. As an official developer for an ASF project (say, Geronimo), you will be granted the ultimate commit karma to the source repository. Everyone can read the source code in the repository, but only official committers can modify or add to the code. There is no way to sign up or enroll to become a committer. To become a committer, you must be voted in by other committers. To earn the trust and approval of other committers, you must first prove your worth. This typically means spending time in the community, helping others, and contributing to the project in the form of a code patches, defect reports, mailing list involvement, and so on. If you are dedicated and capable, the existing committers community will eventually notice your merit and invite you to officially join the project as a committer.

Some of the most common scenarios preventing the use of Open Source software include the following:

  • You cannot find an Open Source project that satisfies your needs.

  • The maturity and reputation of some Open Source projects are questionable.

  • You need dependable support, but no company is offering such a service for the Open Source project you are considering.

  • The expertise for the specific Open Source project that you are considering is not available locally.

  • You cannot abide by the specific licensing terms of an Open Source project (a variety of Open Source licenses are discussed in the next section).

Obviously, some of these issues cannot be readily overcome, and proprietary software may be your only choice. But when it comes to the selection of a robust, scalable, and compatible, J2EE 1.4 container, there is little reason why you would not investigate the possibility of adopting the Open Source Geronimo server.

Not all Open Source software is the same. For one thing, it may be distributed under different Open Source software licenses. This may have implications for how you may or may not use, modify, or redistribute the software. The next section will help you understand some of the most common Open Source licenses available today.


Understanding Open Source Software Licenses

There many different Open Source software licenses out there. These licenses are created to cater to the needs of different combinations of software creators and software users. In most cases, if you are only aiming to use the Open Source software and not to modify and/or redistribute it, the terms of the licenses do not restrict you in any significant way.

Many Open Source software licenses are simply derivatives of one another. There are several well-known groups of Open Source licenses. Each group reflects a large early Open Source project that has since branched out into an entire family of related projects (similar to the growth of the ASF).

While Geronimo is licensed under the Apache 2.0 license, an understanding of the other popular Open Source licenses available is vital for putting in perspective the benefits of Geronimo’s license.

While a comprehensive list of approved Open Source licenses is available from the Open Source Initiative (www.opensource.org), the following are the Open Source licenses that are examined in this section:

  • The MIT license

  • The BSD license

  • The new BSD license

  • The GNU General Public License (GPL)

  • The GNU Lesser General Public License (LGPL)

  • The Apache 2.0 License

The MIT License

This is the classic public domain license. It basically allows any use of the software. It requires all distributions to include the same license. This license only protects the software creator with a “use at your own risk” disclaimer.

The goal of this license is to distribute software freely, allowing any use, yet at the same time protecting the originator from liability caused by its use.

The BSD License

This license was made famous by the early Berkeley Software Distribution (BSD) from the University of California, Berkeley.

The license adds a clause to the MIT license that requires the visible mention and acknowledgment of the source of the original software, with a statement such as, “This product includes software developed by the University of California, Berkeley and its contributors.” This is widely known as the advertising clause.

This license also explicitly restricts adopters of the software from using the name of the organization in promotion of the derived software.

The New BSD License

This is a revision of the original BSD license released in 1999, removing the need for the advertising clause and making it equivalent to the MIT license.

The original license is modified because it turns out that many Open Source software products make use of many (hundreds in some cases) other projects. To comply with the advertising clause, the derivative software often must track and print out hundreds of advertisements.

GNU’s General Public License

This is the GNU General Public License (GPL). The GNU licenses are based on copyleft (a play on the word “copyright”). Copyleft means that the license attempts to enforce that any derivative work, based on the original software, is also free software. This means that if you modify the code of copyleft-licensed Open Source software and you wish to redistribute it, you must also contribute back your modifications to the community as free software.

Copyleft licenses essentially eliminate the possibility for a commercial vendor to adopt the software, modify it, and then sell it as a proprietary solution without contributing it back as open source. The vendor, under copyleft, is obligated to contribute the modified source code as free software, under the same licensing terms.

One of the most prominent users of the GNU GPL is the Linux operating system. This is also the primary reason why all the commercial Linux vendors still make the source code of their enhanced systems publicly available.

The goal of GNU licenses is to ensure that free software stays free, protecting it and discouraging proprietary adaptation or non–Open Source redistribution of the software.

LGPL

This is the Lesser GNU Public License (LGPL), previously known as the Library license. It is a copyleft license. Originally designed for Open Source software libraries, it allows the licensed software to be linked to other software modules that may not be licensed as free software - and does not require the resulting bound unit be contributed as free software. However, many different interpretations of this license do exist.

Because of this allowance, the LGPL is considerably weaker than the GPL in the enforcement of copyleft.

Apache License 2.0

This is the software license of Geronimo, and all new ASF projects. It is a very liberal license, evolved to protect the developers and potential contributing vendors, as well as the software user.

The 2.0 license addresses the following issues:

  • Reuse of the same license text by any project without the need to change wording (ASF or otherwise)

  • Inclusion of the license in a source code file by reference, without fully reproducing all clauses

  • Protection of the licensee (a contributor must provide a patent license if the contribution infringes on patents)

  • Deletion of attribution notices (often required by the originating organization) as part of the license terms (but included in separate notice files)

Basically, the Apache licenses allow you free use of the software for any purpose, commercial or otherwise, including modification and redistribution.

However, you are obliged to include a copy of the license, and all included attributions, with every distribution of the software. You are also forbidden to use the Apache trademark for your own purposes or to suggest that ASF endorses your software in any way.

You are not, however, obliged in any way to contribute your derived software or changes to the original software.

To enable maximal software reuse between Open Source projects, however, the ASF has consciously tried to make the Apache 2.0 license compatible with GNU’s GPL. However, as of today, no legal expert is able to confirm this compatibility.

Important

The Apache License 2.0 is one of the most refined and liberal (yet vendor-friendly) Open Source software licenses in the world. The acceptance of IBM to the terms of the license (for their involvement with Geronimo) is a clear testament to the value and applicability of the license. You are in good company when adopting Open Source software with the Apache 2.0 license.

For more detailed answers to frequently asked questions regarding the Apache 2.0 license, see the FAQ (www.apache.org/foundation/licence-FAQ.html).

Interpreting the Licenses

As mentioned previously, almost all of the licenses allow you to install and use a single instance of the item for personal or commercial use without restriction. They tend to place more restriction on those who need to modify and/or redistribute the software. In case of any doubt, before extensive deployment in an enterprise, you should seek specific legal advice. Only a qualified attorney can give you appropriate legal advice on the selection of Open Source licenses for your own specific purpose.


Summary

Borrowing from the proven-effective strategy for Open Source software development, the ASF sets out to create a certified J2EE container, distributed with the Apache 2.0 license, managed by a meritocracy of server developers, and supported by a community of active J2EE developers/users.

Apache Geronimo was created by a small, but dedicated, group of developers. These developers have demonstrated their technical ability on many other Open Source projects.

Also important in Geronimo’s young history was the participation of IBM. IBM started with the Gluecode Software acquisition, development of a support service for Geronimo users, and the introduction of the community edition of Websphere Application Server (WAS CE) - based on Geronimo. Clearly, IBM has adopted Open Source software with no intention of displacing or subsuming it - instead, profiting only from added value - a business model never seen before from a multinational software vendor that is based purely on services and support.

Open Source software can be attractive to many organizations and enterprises primarily because it is distributed free of charge. In addition, since the source is available, the software can be adapted to specific use, and defects can be corrected by competent in-house developers. The wide availability of source code also means that skilled labor and support services are readily available from multiple sources - even internationally. This ability to have multiple sources for support or developer resources is gaining importance as some enterprises attempts to get out of the single-vendor handcuffs contracted during the prior decade of rapid growth.

There are many variations on Open Source software licenses. The most popular are based on GNU, BSD, or Apache. The GNU software licenses typically allow free use but oblige the user to contribute new enhancements as Open Source software to the community. The BSD software license is very liberal. However, it does require the acknowledgment of software source if the software is resold or embedded into a product. The Apache licenses are recognized by the industry to be the most liberal in existence. Apache licenses allow full commercial use and sale of the software, without any contribution obligations.

Chapter 4 turns its attention back to the Geronimo server and takes a look inside to reveal all of the internal machinery.


Chapter 4: Geronimo’s J2EE 1.4 Components

Overview

Your first encounter with a J2EE-compatible server (like Geronimo) may be daunting. After all, the J2EE 1.4 specification refers to no less than half a dozen of other specifications in mandating the features that must be provided in every compatible server. Geronimo is indeed feature rich. Much of this stems from the rich feature set of the components that are included as part of Geronimo. This chapter demystifies Geronimo by examining the internal composition of Geronimo’s J2EE service component.

This chapter begins with a review of the tiered architecture of a J2EE server, drawing specific references to the services offered by Geronimo. It presents the services and features available at each of the tiers and shows the software components that may be deployed on that tier.

This is followed by a brief discussion of client-side support provided by Geronimo. It introduces the Client Application Container, a feature that facilitates the creation and deployment of J2EE clients.

Another important area covered in this chapter is container services. These are services provided by Geronimo for hosted software components (such as security and transactions). The software modules and components you deploy to Geronimo will be able to make use of these container-wide services. In later chapters, you will discover how to configure the parameters for the container services.

By the end of this chapter, you will be familiar with the composition of the Geronimo server from a J2EE perspective. You will find out the types of J2EE software modules that can be deployed to a Geronimo server. You will also have an appreciation for the configuration customization that can be made when deploying Geronimo applications.


Geronimo and the J2EE Tiered Architecture

Geronimo is a fully compatible J2EE 1.4 server. As such, it includes all the required features and services documented in the J2EE 1.4 specifications. This is a very large set of features, designed to cover the requirements from a highly diverse set of enterprise users.

From an architectural perspective, the features and services provided by Geronimo can be separated into the J2EE tiers, including the following:

  • Web tier

  • Business tier

  • EIS tier

  • Web services

  • Interoperability

  • Client support

Across these tiers, Geronimo also provides a set of valuable container services. These services are features that are available to software components running within Geronimo. These features are configurable by administrators and deployers working with Geronimo. These important container services include the following:

  • Naming and directory

  • Transaction

  • Security

  • Manageability

  • Configuration management

Figure 4-1 illustrates each of these tiers and services, as well as how they interrelate with one another.

Image from book
Figure 4-1: J2EE tiers and container services in Geronimo

The sections to follow describe each of the tiers and services in more detail. You will also discover the Geronimo service components and features on each of the tiers.


Geronimo’s Web Tier

The Web tier is where the user’s browser meets the Geronimo server. Of course, other than users on browsers, an automated program can also make connections to the Web tier for information over the HTTP protocol. Non-browser-based access is typically done through Web services, which is discussed later on in this chapter.

The Web tier is also where most presentation layer components will reside. User interface technologies such as JavaServer Pages (JSPs), JavaServer Faces (JSFs), Struts, Tile, Direct Web Remoting (DWR), Velocity, and Tapestry all work at this tier.

Depending on the server-side configuration, there may be a front-end Web server that forwards requests to Geronimo for processing (see Figure 4-2).

Image from book
Figure 4-2: User access Geronimo through the Web tier

The Web-tier containers in Geronimo, however, are also capable of serving as a standalone Web server if necessary. Figure 4-2 illustrates this as an alternative via dotted lines. For sites where most of the pages are dynamically generated using JSP or other presentation technology, this built-in solution may suffice.

Increasingly, developers are turning toward lightweight server solutions, where the entire application is coded to be executed within the Web container. By leaving out the baggage of the business tier and the EIS tier, a lot of complex coding and large library code can be eliminated in the final application. This allows applications to be distributed and executed with smallest possible memory and disk footprint. Geronimo fully supports these lightweight applications at the Web tier. In fact, Geronimo 1.1 has a Little-G minimal server distribution that can run lightweight solutions with no baggage beyond a Web-tier server (your choice of Tomcat or Jetty).

Components Deployable at the Web Tier

Web applications are made out of software components. The software components that may be deployed as part of application at the Web tier include:

  • Servlets

  • JSP

A servlet is really a Java class coded to special conventions (implementing the Servlet interface). Since a servlet may depend on other Java classes and libraries to operate, the application deployment will always need to include these dependent code modules.

There are many developer frameworks that are built using JSP and servlets. This includes Struts, Tiles, JSF, DWR, Velocity, Tapestry, and so on. Applications built using these frameworks, therefore, can also be deployed at the Web tier.

Before the software components can be deployed to the Geronimo Web-tier container, they must be bundled up in an archive. The J2EE specification requires the modules to be bundled in the JAR format and that they be named with the extension .war. These are called Web application archive (WAR) files. A WAR file needs to be laid out in a very specific format, including a required standard deployment descriptor (web.xml) in the WEB-INF directory within the archive.

Most modern development tools will create WAR files for software projects automatically. As an administrator, you will seldom need to work with a disassembled WAR file. Your development team should supply deployable Web applications in the form of WAR files.

Thus far, Geronimo’s Web-tier container has been mentioned without naming a specific implementation. The next section describes the two choices that you have, when working with Geronimo, for the Web-tier container.

Tomcat and Jetty - Web-Tier Containers

At the Web tier, Geronimo uses two well-known containers:

  • Apache Tomcat

  • Jetty

You have the option, when you download Geronimo, to select either the binary distribution with Tomcat already integrated as the Web-tier container or the binary with Jetty integrated.

Tomcat at the Web Tier

Apache Tomcat is an ASF Open Source servlet/JSP container project. You can get all the project information you need on the official Web site:

http://tomcat.apache.org/

Geronimo 1.1 integrated the latest 5.5 release of Tomcat as its Web container. This version of Tomcat supports the Servlet 2.4 and JSP 2.0 standards. Any Web application coded to these standards can be deployed to Tomcat/Geronimo.

The Tomcat integration supports the following advanced features of the Tomcat container:

  • Multiple simultaneous protocol connectors (HTTP, SSL, AJP1.3, and so on)

  • Virtual hosts

  • Realms

  • Valves

  • Clustering

Furthermore, the Tomcat integration takes advantage of Geronimo’s container services. This integration provides access to the Java Naming and Directory Interface (JNDI), security, and transaction services of Geronimo.

Chapter 11 provides detail information on the configuration of the Tomcat server inside Geronimo.

Jetty at the Web Tier

Jetty is a popular Open Source lightweight servlets and JSP container. Jetty was developed by the principals of MortBay, a company based with offices in the UK and Australia. Jetty is released under the Apache License 2.0. You can get the Jetty project information at the official Web site:

http://jetty.mortbay.org/

Similar to the Tomcat integration, the Geronimo Jetty integration supports the following advanced features of the Jetty container:

  • Multiple protocol connectors (HTTP, SSL, AJP1.3, and so on)

  • Virtual hosts

The Jetty integration takes full advantage of Geronimo’s container services. You will have full access to the JNDI, security, and transaction services of Geronimo when configuring Jetty components.

Chapter 10 provides detailed information on the configuration of the Jetty server inside Geronimo.


The Business Tier

The business tier is where developers create their business logic components. In a J2EE 1.4 server such as Geronimo, the business logic code at the business tier is always encapsulated as Enterprise JavaBeans (EJBs).

Components Deployable at the Business Tier

The only type of software component deployable at the business tier are EJBs. EJBs are specially constructed Java classes coded to the EJB 2.x specification. There are currently three distinct types of EJBs that can reside in the business tier:

  • Session beans

  • Entity beans

  • Message Driven Beans

Of the different types of EJBs, session beans are further divided into stateless session beans and stateful session beans. The session beans exist only in context of a user session. Stateless session beans are typically used to perform operations on entity beans. Stateful session beans maintain state information between invocations; they are useful to hold data that a developer needs to keep around while the application is running but that does not need to be saved to a database.

Entity beans are associated with data stored in a database (typically relational), while Message Driven Beans (MDBs) are called when incoming messages are received by at a specific Java Message Service (JMS) destination.

Figure 4-3 shows the EJBs that can be deployed at the business tier.

Image from book
Figure 4-3: EJBs deployable at Geronimo’s business tier

All of these classifications are more important to application developers than to administrators/deployers.

Most EJBs are prebundled as a module for deployment. Geronimo administrators and deployers work with a bundled archive rather than individual EJBs.

An important thing to realize from Figure 4-3 is that entity beans may require the configuration of a Java Database Connectivity (JDBC) data source for storing the related data, and deployment of MDBs may require the configuration and setup of a JMS destination. Of course, code within the EJB implementation may also reference other business-tier EJBs that may not reside within the same archive bundle.

Deployable Module at Geronimo’s Business Tier

EJBs to be deployed to the Geronimo server must be bundled in an EJB JAR file. According to the J2EE 1.4 specifications, the EJBs must be bundled together with a standard deployment descriptor called ejb-jar.xml, placed in the META-INF directory of the archive.

Deploying EJBs As Part of an Enterprise Application

Most likely, especially in production, the EJBs in an EJB JAR file is just a part of a larger enterprise application. In this case, a WAR file (for the Web-tier components) is combined with an EJB JAR file to create a new archive called an Enterprise Application Archive, or an EAR file. An EAR file is just a JAR file with an .ear extension.

An EAR file can contain one or more WAR files containing servlets and JSPs, and one or more JAR files containing EJBs (as well as other resource adapter JARs). It must include a standard deployment descriptor, called application.xml, in the META-INF directory. This deployment descriptor should reference the modules that are a part of the overall enterprise application.

OpenEJB at the Business Tier

The EJB container inside Geronimo is a special version of the OpenEJB version 2.1 container. OpenEJB is an Open Source EJB container, hosted at Codehaus, that is released under the Apache 2.0 license. For more information on OpenEJB, see:

http://openejb.codehaus.org/

The OpenEJB container integration within Geronimo features the following:

  • Support of EJB 2 Container Managed Persistence 2

  • Support of EJB QL

  • Support of EJB 2.1 Web services interoperation

  • CORBA interoperation

The specially adapted OpenEJB container inside Geronimo makes full use of Geronimo’s container services. This includes JNDI support, fully configurable transactional support and security.

Chapter 12 will provide detailed information on the configuration and deployment of EJBs (either alone in an EJB JAR or as a part of an EAR) to the OpenEJB container.

ActiveMQ at the Business Tier

To provide support for MDBs and general message queues (MQ) services for software components, Geronimo uses ActiveMQ. ActiveMQ is a very popular Open Source message queues broker implementation. ActiveMQ provides a JCA 1.5–compatible resource adapter, which is integrated into Geronimo. This allows application developer to use the convenient JMS API to access all the features of ActiveMQ.

ActiveMQ supports MDBs by accepting inbound connections. This means that messages sent to a message destination (such as a JMS topic or queue) can be used to trigger a call to an MDB. This support is leveraged by Geronimo in its MDB implementation.

Chapter 16 provides more details on configuration of ActiveMQ at the business tier.


The EIS Tier

The EIS (Enterprise Information Systems) tier of the J2EE model is all about interfacing to external systems. More specifically, this tier contains technologies and software components that are used to connect to other systems in the enterprise.

The types of EIS systems to which you might need a connection include:

  • Relational database management system (Oracle, DB 2, PostgreSQL, MySQL, and so on)

  • Message queue system (MQ series, ActiveMQ, and so on)

  • Legacy system (mainframe computers, minicomputers)

At the EIS tier, the main objective is to allow the J2EE software components to interact and leverage external systems. It must be flexible and adaptive in the integration of these additional systems, both present and future. This tier is the portal from the J2EE server into other enterprise assets (data, computing capabilities, and so on) that are not available within the pure Java environment.

The J2EE solution to this problem is to enable plug-ins. The concept is familiar. Instead of having very specific ability to connect to very specific systems, J2EE provides a connector architecture - a driver interface, if you will. Basically, any vendor or developer then can write a connector (driver) that plugs into the EIS tier to access any external system. The only requirement for the connector/driver is that it is written to the Java Connector Architecture (JCA) 1.5 standard.

This strategy has been proven to be very effective. To access relational databases, a JDBC connector is supplied in Geronimo. This connector has the unique ability to work with any JDBC-complaint drivers, allowing applications in Geronimo to talk to major RDBMSs (such as Oracle, DB2, PostgreSQL, and MySQL) right out of the box.

Another important connector that is supplied in Geronimo is the ActiveMQ JCA 1.5 resource adapter. This connector allows applications running on Geronimo to access message queues (MQs) handled by the ActiveMQ message broker via the standard JMS APIs. To connect to other MQ systems, this can be done indirectly through ActiveMQ, or via a JCA 1.5 connector for the target MQ system.

The capability to interface to legacy systems, although logically belonging to the EIS tier, is classified as part of container services - interoperation. The main enabling technology here is the capability to talk to CORBA-based systems.. The Interoperability tier is discussed later in this chapter.

Figure 4-4 shows the components associated with JCA 1.5 support at Geronimo’s EIS tier.

Image from book
Figure 4-4: Geronimo’s JCA 1.5 and EIS tier services

The following section describes the components depicted in Figure 4-4.

ActiveMQ at the EIS Tier

Geronimo integrates ActiveMQ on the EIS tier in two ways:

  • The ActiveMQ JCA 1.5 resource adapter is available to access any ActiveMQ broker instance.

  • An instance of the ActiveMQ broker is configured as a service running in the default full J2EE Server download configuration of Geronimo.

An ActiveMQ resource adapter is a driver that can be used to access a message broker. An ActiveMQ message broker is the actual server that manages and coordinates the message queues.

With the JCA 1.5 resource adapter, application components deployed at the Web and business tiers have access to the message queue functionality provided by any ActiveMQ message broker. Developers can code to the well-known JMS APIs. Of course, the easiest broker to use will be the one hosted in Geronimo.

The instance of ActiveMQ message broker hosted in Geronimo can be configured directly through Geronimo (Web console or config.xml). Chapter 16, provides more details on configuration of ActiveMQ broker.

Derby at the EIS Tier

Geronimo has a built in JCA 1.5 connector for JDBC. This enables the application components at both the Web and business tiers to access any relational database that has JDBC support. Almost all of the major vendors (including Oracle, IBM DB2, Microsoft SQL Server, PostgreSQL, and MySQL) have excellent support for JDBC.

Geronimo also has its own built-in relational database system. Geronimo’s built-in server is an instance of an Apache Derby database. Apache Derby is a 100 percent Java implementation of a full-featured relational database system. Derby actually evolved from code donated by IBM. IBM continues to market a version of Derby called Cloudscape.

Developers code to the standard JDBC APIs. As an administrator, you can configure the Derby instance hosted by Geronimo. You can also configure data sources for software components via the JDBC connector for access to the internal Derby or another external RDBMS.

Chapter 13 will provide more details on the configuration of Geronimo data sources for external RDBMSs.

JavaMail for Integration to Email Systems

Another feature of Geronimo that logically belongs in the EIS tier is the JavaMail integration. JavaMail is a simple API for software components to work with email messages. Geronimo has an implementation of JavaMail built in and enables applications to access SMTP-based email servers. Developers can code their components to the standard JavaMail 1.3 APIs.

As an administrator, you may want to configure the Simple Mail Transfer Protocol (SMTP) server location(s). Chapter 12 has coverage on the configuration of JavaMail parameters for Geronimo.


Web Services

Web services is one of the most flexible means to connect between client applications and back-end server applications over a network (and, in particular, the Internet). The operation of Web services rides on top of the standard Hypertext Transfer Protocol (HTTP) protocol, the same protocol that enables today’s Internet to flourish. Web services works on the exchange of XML-based messages. XML messages are text messages in a well-defined descriptive format. Text messages are human-readable, and easy to generate or process using most programming languages. The main advantages of communications through Web services include the following:

  • The HTTP protocol is ubiquitous; clients can live wherever Web browsers will work.

  • XML messages are easy to generate and process, and are independent of programming languages, operating systems, or hardware.

  • HTTP tunneling through firewalls is a well-known and stable technology, allowing Web services clients to work behind firewalls.

  • The available Web services on a server can be described in XML, and this list of services can be discovered dynamically by potential clients.

  • It is possible to create technology that dynamically discovers the methods of a Web service interface, then generates the code required to access these methods dynamically - freeing the client developer from tedious code writing.

The J2EE 1.4 specification mandates the support of Web services by all compatible containers. Geronimo supports Web services through the use of Apache AXIS and some custom coding.

AXIS and Web Services

Apache AXIS is the Simple Object Access Protocol (SOAP) engine in the ASF XML-based project family. AXIS includes a set of libraries and tools to create Web services or Web service clients using the Java programming language. You can find more on this at the following Web site:

http://ws.apache.org/axis

Geronimo integrates AXIS to provide a variety of features for software components at all of the J2EE tiers. The next section describes this integration.

Geronimo Web Services Integration

Web services support within Geronimo permeates throughout the different tiers. Table 4-1 provides a synopsis of this support.

Table 4-1: Geronimo Web Services Support
Open table as spreadsheet

J2EE Tier

Web Services Support

Web tier

Web services created with SUN’s Java Web Services Development Pack (JWSDP) can be readily deployed on Geronimo. Servlets can implement the Web service logic with generated client endpoints.

Geronimo’s Web services support is an implementation based on the Apache AXIS engine - and tracks the AXIS features set. AXIS is the same Java Web service engine used by other Open Source application servers.

Geronimo’s support is compatible with the Web services specification.

Business tier

OpenEJB supports EJB 2.1 interfaces. EJB 2.1 interfaces can be configured to be service endpoints and exported as Web service interfaces.

This literally means that any EJB can be exposed as a Web service through configuration. In practice, however, it is typically only useful to expose stateless session beans as Web services.

EJBs that needs to access external Web services can do so via Geronimo’s built-in AXIS libraries.

Figure 4-5 illustrates how Geronimo enables incoming Web services requests to the business tier EJBs, or the Web-tier Web service implementation.

Image from book
Figure 4-5: Geronimo support for incoming Web service clients

Figure 4-6 shows how Geronimo support the access to external Web services from either the Web tier or the business tier.

Image from book
Figure 4-6: Geronimo support for component access to external Web services

Chapter 14 discusses the details on configuration of Web services and how to configure EJB for access as Web services.

UDDI Support

Geronimo integrates Apache Scout and jUDDI (pronounced “Judy”) to support access to external Universal Description, Discovery, and Integration (UDDI) server. jUDDI is an implementation of a UDDI service in Java. Following is the project Web site for jUDDI:

http://ws.apache.org/juddi

You can consult the Web site for more information on jUDDI. This feature is a preinstalled application module with the full J2EE server download of Geronimo server.


Interoperability Features

Interoperability is important in many large enterprise installations of J2EE servers. Specifically, interoperability refers to the ability of software components between dissimilar software or hardware systems to talk with one another.

Difference between J2EE EIS Tier and Interoperability

This is quite different from the features on the EIS tier. While the EIS tier enables the Geronimo-hosted software components to access external systems (which are typically monolithic systems that are not component-based), interoperability features enable two-way communications between Geronimo software components and the external software components. In other words, interoperability implies a more fine-grained and tightly coupled interaction than the EIS-level access. EIS tier refers to access to systems such as relational databases and message queues, while interoperability refers to component-to-component interactions.

CORBA Interoperability

When a client application talks to an EJB in Geronimo, the default protocol used is a proprietary one. This protocol is used by OpenEJB to efficiently access the EJB container. When using this protocol, however, you are restricted to access only via Geronimo J2EE clients.

Through interoperability support, Geronimo extends the accessibility of EJBs for non-J2EE clients and Common Object Request Broker Architecture (CORBA) clients.

CORBA is an interoperability standard based on a specification from the Object Management Group (OMG). The OMG is a group made up of hundreds of global companies, institutions, and individuals who are actively deploying OMG technologies - primarily CORBA. The mission of CORBA is to enable systems with dissimilar hardware, operating systems, and programming languages to work together. The CORBA specification itself is very mature, and working implementations of CORBA exist for many mainframe, industrial control, scientific, and defense applications. You can find more information on CORBA at:

http://www.omg.org/gettingstarted/history_of_corba.htm

The interoperability support in Geronimo 1.1 is performed mainly through RMI-IIOP in JDK 2. RMI-IIOP allows Remote Message Invocation (RMI) based software components to communicate with CORBA clients or servers.

With Geronimo CORBA interoperation, CORBA client applications may access Geronimo-hosted EJBs, and Geronimo-hosted EJBs may access external CORBA-based services.

In addition to communication between CORBA and J2EE components, Geronimo’s implementation also includes a security implementation. The security implementation is the Common Security Interoperation Version 2 (CSIv2) that is specified for CORBA 2.3 and later systems. CSIv2 provides secure, authenticated communications between CORBA- and Geronimo-hosted J2EE components.

Figure 4-7 shows the CORBA interoperability afforded by Geronimo.

Image from book
Figure 4-7: Geronimo’s CORBA interoperation support

As an administrator, you can configure EJB for CORBA client access; you can also assist in configuration of external access to CORBA components. Chapter 14 shows how to configure Geronimo CORBA inter-operations.


Support for Application Clients

One important part of the J2EE 1.4 specification describes the required support for application clients.

The client application container, a part of the Geronimo distribution, greatly simplifies the creation of J2EE client applications for Geronimo.

Not all client applications can make use of the client application container, however. Typically, the following types of clients can make use of the container:

  • J2EE applications with a command-line user interface

  • J2EE fat-client applications with a Swing/AWT/SWT (or equivalent GUI library) user interface

  • Java Webstart (JNLP) launched applications that features a GUI user interface

Some examples of clients that cannot take advantage of the client application container but need to use other Geronimo support technologies to access the server (interoperability, Web services, a servlet, JSP, and so on), include:

  • Web browser-based user interfaces such as Ajax

  • Applet-based user interfaces

The main function of an application client container is to provide useful container services to the application client. Ideally, these services should be presented in a transparent manner to the application client. In other words, the code used to access a Geronimo component (say, an EJB) should be the same whether it resides on the client side or on the server side.

The Geronimo client application container provides the following client-side container services to the application client:

  • JNDI lookup of resource references

  • Security service for client-side authentication support

When the client calls on these services, the client application container will transparently communicate with the Geronimo server to retrieve the necessary information.

Figure 4-8 illustrates the functional role of the client application container for Geronimo.

Image from book
Figure 4-8: Geronimo’s client application container

The client application container can be configured using a client deployment plan. Geronimo administrators should be familiar with the configuration of the Geronimo client application container.


Geronimo Container Services

The Geronimo server provides a rich set of container services for the use of the servers and components running inside Geronimo. Some of these services are also extended to the client application container, for use by application client code.

Naming and Directory Service

In a J2EE 1.4 system, the naming and directory service is accessed through the standard JNDI APIs. Geronimo provides a JNDI-compatible set of APIs to access the namespace containing all of its contained components. Figure 4-9 shows the operation of the Geronimo naming service.

Image from book
Figure 4-9: Naming service support in Geronimo

In Figure 4-9, the Geronimo kernel gives every managed Geronimo component a name and registers it with the object lookup service inside Geronimo. A JNDI API implementation is available inside Geronimo to query the lookup service. These components can then be looked up and referenced throughout the Geronimo server using JNDI - by the different services, with any custom application code, or in configuration files that administrators create.

This means that one component can look up another component through JNDI. This capability is heavily used inside Geronimo. All Geronimo components are named according to the JSR-77 standard. This JSR specifies a convention for naming that, while convoluted for human to comprehend, is very efficient for computer to maintain and manage.

Naming service support is a quintessential feature of Geronimo. As Geronimo administrator, you will work frequently with the configuration of object name and references. Chapter 7 provides substantial details on the internal object naming convention used by Geronimo services.

The JNDI API can also be used by software components to locate configured J2EE resources, such as pooled JDBC connections or JMS destinations. A Geronimo administrator can configure these resources during deployment time. Chapters 13 and 16 provides details on such configuration.

Transaction

Geronimo supports declarative and programmatic transactions for deployed application components. Declarative transaction means that the component code itself does not deal directly with transactions. Instead, transaction boundaries can be specified during deployment time, by specifying them in a standard J2EE deployment descriptor.

A programmatic transaction is carried out by the application code. Applications can use a standard API (called JTA) to program its transaction. Programmatic transaction boundaries are typically of interest only to developers.

For many J2EE applications, the way to add a transaction to the application is via a declarative transaction during the deployment of the EJBs.

As an administrator, you should understand the options available for controlling transaction boundaries, and be familiar with the XML elements that control transaction boundary for deployment.

In Chapter 12, the deployment descriptors and elements that control transaction boundaries are examined.

Security

Geronimo supports container-wide security realms through the implementation of the Java Authentication and Authorization Service (JAAS), and an implementation of the Java Authorization Container Contract (JACC). This basically means that Geronimo can provide a variety of means (subject to plug-in modules) to authenticate a user before allowing access and then to authorize specific access based on user credentials.

There is a set of XML elements that can be used to configure security on most Geronimo resources being accessed (such as a JSP page, a servlet, an EJB, or a particular method of an EJB). These are the same elements regardless of the actual resource being protected - thanks to the container-wide uniform support of the security mechanism/policies. As an administrator, you should become familiar with this versatile set of security elements.

Chapter 15 provides a from-scratch overview of the security mechanisms packaged into Geronimo. You will also see how to use the security elements in the various deployment plans throughout Geronimo.

Manageability

Management of the Geronimo server, and visibility to all of its contained components, can be accomplished through Java Management Extension (JMX) APIs. JMX provides component-level management features based on manageable components called MBeans. The idea is for manageable software components to expose their manageable features through the properties and operations of an MBean. The JMX infrastructure can then coordinate the availability of the exposed information to a management tool or client application.

Every single Geronimo component can be optionally configured to be manageable by the developer. Since Geronimo does most of the work in making a component manageable, many component developers will take advantage of the opportunity. This is especially true for the suite of components that provide the essential J2EE services. Components such as the Tomcat or Jetty Web-tier servers are components that are created to be completely manageable.

As an administrator, you can gain access to this manageability through the use of the Web console, debug console, and jConsole (available in Java SE 5) tool. These tool displays many of the exposed properties and operations of the Geronimo server components to the administrator. The Web console in particular also enable configuration of the server components.

Chapter 7 shows the use of the debug console and jConsole to view managed components and their managed properties. Chapter 8 shows how to use the Web console to access and configure many of the managed components and their properties.

Configuration Management

With Geronimo, configuration management is a built-in feature that is pervasive throughout its design.

Every configured and deployed module in Geronimo is associated with a configuration. Geronimo manages these configurations, and relationships between configurations internally. This allow you to deploy, undeploy, and redeploy the modules with ease.

All Geronimo configurations are serializable. This means that the same configuration can be restarted, or transferred to a similar server and started. This ability to move configurations between machines is one of the many by design scalability features that is built into Geronimo. Geronimo takes advantage of this feature in its implementation of the Geronimo plug-ins. Chapter 17, an electronically downloadable bonus chapter from http://www.wrox.com, covers Geronimo plug-ins in more details.

As an administrator, you deploy and undeploy application modules to the Geronimo server. Each time add or remove modules on a Geronimo server instance, the set of managed configuration changes. Geronimo always maintains an image of the current set of configurations via a combination of the config.xml file and serialized binary image in the repository. It is often important, as an administrator, to be able to set the server to some known-good “base” state should a deployments fail catastrophic manner and cause server instability. This can be accomplished by keeping backup copies of known-good config.xml file.


Summary

Geronimo is a very large J2EE 1.4-compatible server. To create its J2EE personality, the developers of Geronimo brought together many service components from all over the ASF’s project tree. These service components can be classified according to the J2EE architectural tiers.

At the Web tier, the containers integrated into Geronimo are Jetty and Tomcat. You can select one or the other by downloading different distribution of Geronimo. These service components handle JSP, servlets, and popular developer frameworks such as JSF and Struts.

At the business tier, the containers integrated into Geronimo include OpenEJB and ActiveMQ. OpenEJB can host EJB written to the EJB 2 standard, including Component Managed Persistence (CMP2). ActiveMQ can host Message Driven Beans (MDBs), a type of EJB that responds to asynchronous incoming messages.

At the EIS tier of the J2EE architecture, Geronimo supports JCA 1.5 resource adapters. It leverages JDBC and can connect to any compliant RDBMS. Internally, Apache Derby is a Java-based RDBMS that is bundled. Connection to Message Queue service is also made possible via tight integration with ActiveMQ. JavaMail is also available at this tier for applications that interact with or generate email messages.

To support Web services, Geronimo has Apache Axis integrated. UDDI support, part of Geronimo’s feature set, is provided by jUUDI.

To interoperate with legacy systems, Geronimo has built-in CORBA interoperability, including CORBA’s CSIv2 security support.

Last, but not least, Geronimo features a client-side application client container that greatly simplifies the creation of J2EE client applications.

Geronimo provides running applications with a set of container services. These services include naming, security, transaction, manageability, and configuration management.

The entire J2EE 1.4 stack of components and services stands ready to serve your server-side needs in Geronimo. You may be curious to how the server works with all these integrated components. Many of your questions will be answered by the next chapter.

Chapter 5 covers the general architecture of the Geronimo server, together with the directory structure used by the server.


Chapter 5: Geronimo Architecture and Directory Structure

Overview

Chapter 4 introduced Geronimo as a J2EE server. An under-the-hood exploration reveals the J2EE components inside the Geronimo server. What may not be evident, however, is that Geronimo is not limited to being a J2EE server from the architectural point of view. In fact, J2EE server is just one of the many different personalities that a Geronimo server can take on. This chapter sets the facts straight and examines the internal architecture of the Geronimo server.

Understanding the architecture of Geronimo is vital for administrators and deployers, because it allows you to leverage the flexibility built right into the very core of Geronimo. Namely, the concepts of GBean, module, and assembly are pervasive throughout Geronimo. This chapter introduces these concepts from scratch and shows how the Geronimo server is divided internally into components.

Configuration management is a key feature that Geronimo provides to all its components. This chapter explores this very important concept. Installed modules are stored (between reboots of the server) in a repository. The Geronimo repository is where Geronimo keeps all its service components and dependent libraries, as well as module configuration information. The chapter provides a detailed account of how the repository works in Geronimo.

The repository is kept as part of Geronimo’s directory structure. This chapter explores this directory structure in detail, showing the subdirectories, their contents, and their purpose with respect to the server’s operation.

This chapter also revisits the config.xml file that you examined in Chapter 2 and goes further in depth on the GBean customization options that this file provides.


GBeans in Geronimo

You may have heard that Geronimo is all about GBeans. This simplified generalization is actually not too far from the truth.

A GBean is a Geronimo-Bean. In fact, all of the software components running inside a Geronimo server are GBeans. Like a regular JavaBean, a GBean has properties that can be accessed, and methods that can be invoked. Figure 5-1 provides an overview of a running Geronimo server.

Image from book
Figure 5-1: Running Geronimo server comprises GBeans and a kernel

In Figure 5-1, note the following two sets of architectural components that make up a running Geronimo server:

  • Geronimo kernel

  • GBeans

If you could actually take a look inside a running Geronimo server, you would see that GBeans make up the bulk of the executing code, while the kernel occupies a very small footprint and is a very thin core layer of code.

The Geronimo kernel provides the GBean components with well-defined kernel-provided services. This set of services includes the following:

  • Configuration management

  • Lifecycle management

  • Manageability implementation

Each GBean hosted inside Geronimo can take advantage of any of these kernel-provided services.

GBeans and Modules

The Geronimo kernel provides GBeans with a configuration management service. In a nutshell, configuration management is the ability to handle specific grouping of GBeans as individual units.

Essentially, the Geronimo kernel can wire up a bunch of GBeans to form a larger grouping called a module. The kernel can provide the capability to persist these modules to permanent storage or to reconstruct the GBean grouping from a persisted image.

In creating a Geronimo configuration, you can alter the run-time behavior of a GBean by setting attributes to specific values. For example, a Tomcat HTTP 1.1 connector may be a GBean within the Tomcat server module. You may set the port number used by the connector by setting the value of the port attribute on this GBean. A module (or a specific configuration of a grouping of GBeans) in Geronimo is specified in a deployment plan. The deployment plan spells out in detail how a set of GBeans is to be configured together (the specific values for the GBean attributes and how they are related to one another).

Some readers may recognize this style of GBean wiring as very similar to the components wiring mechanism of the Spring Framework (an Open Source component system wiring framework - see www.springframework.org ). Indeed, Geronimo’s XML-based component wiring mechanism is inspired by Spring.

Figure 5-2 illustrates how the Geronimo kernel performs configuration management.

Image from book
Figure 5-2: Geronimo kernel configuration management service

In Figure 5-2, you can see that Module 1, Module 2, and Module 3 all consist of different GBeans running. For example, you may think of Module 1 as a Web application running in Tomcat, while Module 2 is a bunch of EJBs you have deployed to OpenEJB, and Module 3 may be a Web service that you have deployed in Geronimo.

Once the modules are deployed to the Geronimo server, the kernel keeps a image of the configuration in the repository. This allows the kernel to quickly restore the running configurations when the server restarts.

Later in this chapter, the section Configuration Management with Geronimo provides more details on how module images are kept in the Geronimo repository.

GBean Lifecycle Management

All the J2EE server components that you have seen in Chapter 4 are actually composed of GBeans. GBeans are the smallest chunk of code that the Geronimo kernel works with. The lifecycle of a GBean is managed by the Geronimo kernel. This means that the kernel can create a GBean instance and start, stop, and destroy it at any time.

Conceptually, then, the Geronimo server is able to deploy, start, and stop modules. Modules consist of grouping of GBeans. The Geronimo server starts and stops these groups of GBeans via its kernel.

GBeans and Manageability

A GBean can optionally expose attributes and operations (properties and methods, in system-management terms) through a Java standard management interface called Java Management Extension (JMX). (See http://java.sun.com/products/JavaManagement/index.jsp.) The Geronimo kernel provides this manageability service to any GBean that wishes to take advantage of it. The creator of the Geronimo GBean needs to write very little code to enable this manageability capability. Not all GBeans take advantage of this capability, however.


Geronimo Modules and Assemblies

It should become clear that since Geronimo server components are all modules composed of GBeans, you can readily mix and match the different server components to create different versions of Geronimo. If this is the way you’re thinking, you understand the essence of Geronimo. In fact, an entire chapter (Chapter 18) is devoted to this very important topic.

For now, you should realize that the J2EE server you get when you download Geronimo is only one of the infinite number of personalities that the Geronimo server can take on. Little-G, the minimal server download, is another possible personality. Each of these personalities is called an assembly in Geronimo.

It is this J2EE server assembly (a specific combination of modules) that is J2EE 1.4–certified. In fact, other famous Geronimo assemblies exist. You may have heard of (or worked with) the Gluecode server or the IBM Websphere Application Server Community Edition. These are two famous Geronimo assemblies that are made into actual commercial products.

An assembly, then, is a grouping of a modules (a combination of server components) that provides a Geronimo instance with its feature set - and hence its personality. Assemblies are the different ways you can create a server out of the various server components available to Geronimo.

For example, you may want to put together a Web-tier-only server. For this, you will probably include either Jetty or Tomcat and leave out OpenEJB and ActiveMQ. You can create a custom Geronimo assembly for this. The end result will be a lighter-weight server occupying less disk space and memory. The Geronimo developer has created this very assembly; it can be downloaded as the Little-G minimal server.

Creating new assemblies is an involved task that requires the downloading of the Geronimo source code and a rebuild of the Geronimo server using a Java compiler. Chapter 18 covers this advanced process in more detail.

Both assembly and modules are cornerstone grouping mechanisms within the Geronimo architecture. Table 5-1 summaries the features of these two important concepts.

Table 5-1: Assembly versus Modules Open table as spreadsheet
Grouping MechanismItems | Being Grouped | Occurs at | Additional Comments
Assembly | Modules | Geronimo Build time | Modules comprising an assembly are specified in system deployment plans.
Module | GBeans | Geronimo server run time | Wiring and GBean attributes parameterization specified in deployment plans.

In Table 5-1, one very important thing to note is that assemblies are bound together at Geronimo build time. This means that the composition of Geronimo assemblies cannot be easily altered without rebuild (from source code) of the Geronimo server.

Since the composition of an assembly is fixed, the code of the server components in an assembly (together with all the APIs libraries that they may be dependent on) can be organized for optimal access during run time. This organization results in the creation of a repository of code and dependent library modules associated with an assembly. You will find the executables of all the familiar server components (such as Tomcat, Jetty, ActiveMQ) all located in the repository. These libraries and code modules in the repository will not change, unless the assembly is rebuilt.

The idea of maintaining modules and dependencies in a repository is not the Geronimo team’s invention. Instead, it is a best practice that originated from the Maven (now Maven 2). Maven 2 is another Apache project (details at http://maven.apache.org ). Maven is a project-building and -management framework. Geronimo designers borrow best practices from Maven-including the repository, the module ID concept, plug-ins, and so on.

The remainder of this chapter examines the directory structure used by Geronimo in great detail and will cover the content of the repository along the way.


Geronimo Directory Structure

The directory structure created by the Geronimo installation provides a glimpse into the internal workings of Geronimo. It is within this directory structure where the Geronimo server places all the code, configuration, and persistent execution state.

In the following examination of the directory structure, you will discover how server components and components states are maintained by Geronimo.

The Installation Directory

Under this directory, you will find the following subdirectories:

  • bin - Directory for binary executable.

  • deploy - The hot deployer regularly scans this directory for modules to deploy. Any modules placed in this directory will be automatically deployed.

  • docs - Documentation directory for Geronimo.

  • lib - Location of essential libraries required for Geronimo’s operation.

  • repository - Directories where Geronimo persists all installed modules, including system modules, as well as the binaries and libraries that they depend on.

  • schema - XML schema for all the run-time deployment plans and deployment descriptors.

  • var - Working directories for Geronimo and all the deployed modules. Artifacts are created during module run time, and may remain after server shutdown (depending on the module’s behavior).

The content of each of these directories will be examined in the subsequent sections.

Important

While it is necessary for you to be acquainted with the directory structure, there is no immediate need to commit anything to memory. As you work with Geronimo, you will be roaming extensively throughout this directory architecture. Before long, it will become second nature as to where things are located.

The bin Directory

This is the directory for the major binary executables in Geronimo. Here, you will find the executables shown in Table 5-2. They are all JAR bundles, and you can run these executables using the -jar option of Java, with the following command-line format:

java -jar <executable name> <arguments>
Table 5-2: Contents of the bin Directory Open table as spreadsheet
Executable | Description
client.jar | This is the executable of the Geronimo client application container.
deployer.jar | This is the executable of the Geronimo run-time deployer. See Chapter 6 for detailed description of how to use this tool.
server.jar | This is the Geronimo server executable. You have already used this executable earlier to deploy the first Geronimo application.
shutdown.jar | This executable can be used to cleanly shut down a running server instance.
upgrade.jar | The upgrader utility to automatically convert Geronimo 1.0.x deployment plans to compatible Geronimo 1.1.x plans. Geronimo 1.0.x used a now obsolete module ID scheme. In Geronimo 1.0, modules were called configurations. You may find some old literature on the Internet still referring to modules as configurations.

Options for each of the executables will be covered in detail when they are introduced in later chapters.

There are also helper batch files (.sh for *nix and .bat for Windows) in this directory to set the command-line environment variables and to simplify launching of these executables.

The deploy Directory

Any deployable archive you placed in this directory will be detected and automatically deployed to the Geronimo server. In addition, the hot deployer continues to monitor the modification date of these archives. If they should ever change (indicating that the archive has been modified), they will be redeployed to the server.

Immediately after installation, this directory is empty. This directory is most useful during testing of Geronimo applications by developers. Developers can simply configure their build tool or IDEs to generate deployable archives into this directory. Geronimo will take care of keeping the deployed module in the server up to date (and redeploy as necessary).

The docs Directory

This directory is where the documentation for Geronimo is stored. As of Release 1.1, this directory contains a single file. This file simply says that you can get all the latest related documentation at http://geronimo.apache.org.

The lib Directory

This is where Geronimo will locate its system libraries at run time. In Java terminologies, these libraries are found at the Geronimo’s system class loader.

Table 5-3 describes the library files that you will find here.

Table 5-3: Library Binaries Used by the Geronimo System Open table as spreadsheet
Library File | Description
cglib-nodep-X.X.X.jar | The code generation library used to manipulate Java byte code by Geronimo.
commons-cli-X.X.jar | Apache commons command-line processing library, used by Geronimo command-line tools (deployer, server, client, and so on) to accept and process the command line.
commons-logging-X.X.X.jar | Apache commons logging library. Provides a uniform layer of APIs for the Geronimo code to log operational problems and exceptions. This library allows a variety of logging implementations to be plugged in. Geron-imo uses log4j for logging by default.
geronimo-common-1.X.jar | Geronimo common library.
concurrent-X.X.X.jar | Concurrency utility library used to create and manage threads and synchronization by Geronimo.
geronimo-deploy-jsr88-X.X.jar | The JSR88 specification APIs.
geronimo-deploy-tool-X.X.jar | The command-line deployer tool libraries.
geronimo-deployment-X.X.jar | Deployment support and utilities library.
geronimo-spec-j2ee-deployment-X.X.jar | The standard J2EE deployment interfaces and APIs.
geronimo-kernel-X.X.jar | The kernel of Geronimo itself.
geronimo-spec-qname-X.X.jar | The standard J2EE naming interfaces and APIs.
geronimo-system-X.X.jar | The binaries of the Geronimo system module.
Geronimo-util-X.X.jar | The binaries of utility libraries used by the system module.
log4j-X.X.X.jar | Binary implementation of the log4j logger.
mx4j-X.X.X.jar | Binary implementation of the MX4J, an Open Source clean-room implementation of JMX.
mx4j-remote-X.X.X.jar | Binary implementation of JMX remoting for use with MX4J.
xpp3-X.X.X.jar | Small, fast, and efficient XML parser (used internally by Geronimo) that implements the XmlPull API.
xstream-X.X.X.jar | XML serialization library used internally to serialize objects to and from XML representations.

You will also find two subdirectories here, containing additional standard Java extension libraries: endorsed and ext.

The endorsed Subdirectory

The endorsed subdirectory contains the XML support libraries that are part of JDK 5 but not part of JDK 1.4.2. The libraries enable applications that make use of the Java XML APIs to run without change on either JDK 5, or JDK 1.4.2. Table 5-4 describes the content of the endorsed subdirectory.

Table 5-4: Content of the endorsed libraries Subdirectory Open table as spreadsheet
Library File | Description
xercesImpl-X.X.X.jar | The Xerces XML parser.
xmlParserAPIs-X.X.X.jar | The standard JAXP XML parser API definitions.

The ext Subdirectory

This is the directory in which to place JSE standard extension libraries that may be required by application modules. There are currently no standard extensions (with the default distribution) in this directory.

The repository Directory

As mentioned earlier in this chapter, Geronimo is actually an integrated server consisting of many individual component servers. For example, Tomcat and OpenEJB are two servers that are integrated in Geronimo. Each of these servers is an Open Source project in its own right and depends on a large set of software libraries for its own operation.

To run all the integrated component servers properly, Geronimo must manage and ensure that the dependent library files are available to the components when they run. Geronimo maintains a copy of the required libraries in the repository. As mentioned previously, a repository is a location where the binaries of the component servers (as well as their own dependent libraries) are maintained. In addition, the repository is also where you will find Geronimo’s configuration store - a place where Geronimo saves the configuration state of the installed and deployed system and application modules.

The repository consists of a large collection of artifacts. An artifact can be considered a single item that can be stored or retrieved from the repository. Each and every artifact can be located in the directory precisely via its coordinates:

  • group id

  • artifact id

  • version

  • type

If this looks familiar, it should. This is exactly the composition of a module ID. This allows modules to be stored into the repository as a type of artifact.

In general, you can find an artifact in the repository by looking into the directory:

repository/<group id>/<artifact id>/<version>

For example, to find the Tomcat server component of the Geronimo server, which has coordinates:

  • group id = geronimo

  • artifact id = geronimo-tomcat

  • version = 1.1

  • type = jar

This means that you can find the artifact if you look under the following directory:

repository/geronimo/geronimo-tomcat/1.1

Indeed, you will find the geronimo-tomcat-1.1.jar artifact there.

Not all artifacts are stored as archive files. Artifacts can be of different types. Some of the popular artifact types are shown in Table 5-5.

Table 5-5: Format of Artifact Storage in the Repository Open table as spreadsheet
Artifact Type | Artifact Storage in Repository
JAR | Stored as archive in repository
WAR | Stored as archive in repository
EAR | Stored as archive in repository
RAR | Stored as archive in repository
CAR | (configuration archive) Stored as a subdirectory in repository

The artifact type of note above is CAR. In fact, when you deploy a module and you specify a deployment plan for the module, the module ID always has the type CAR. A CAR, then, consists of the configuration information for the GBeans within a module, as well as a specification of its dependencies.

By letting the repository store both code archives (such as JAR, WAR) as well as configuration information (in CAR), the repository becomes both a code store and a configuration store.

The binary code of the Geronimo server modules (as well as their dependencies) are all stored as artifacts in the repository.

Table 5-6 describes the top level subdirectories (for release 1.1) under which you find all artifacts. For tools that access the repository in the standard way, the top-level subdirectory represents the group id of the coordinate for locating an artifact uniquely.

Table 5-6: Top-Level Directories of the Geronimo Repository Open table as spreadsheet
Subdirectory (group id) | Description
activeio | The IO libraries for ActiveMQ.
activemq | The binaries and libraries for ActiveMQ message broker and resource adapter.
antlr | The binaries for the Open Source antlr grammar parser generator.
asm | Binaries and library for class working toolkit.
axis | Binaries and library for the Apache Axis SOAP engine, handling Web services in Geronimo.
cglib | Binaries and library for the cglib byte code generation and manipulation library.
common-beanutils | Apache common beanutils; used by many Open Source libraries.
common-cli | Apache common library for processing command lines.
commons-collections | Apache common collections; used in many Open Source packages and libraries.
common-digester | Apache common digester; used by many Open Source libraries.
commons-discovery | Apache common discovery; used in many Open Source libraries.
commons-el | Apache common expression language; used in many Open Source products.
commons-logging | Apache common file upload library; used by many Open Source libraries.
commons-modeler | Apache commons modeler; supports JMX; used in many Open Source libraries.
concurrent | The oswego util.concurrent library, a versatile library for creating multi-threaded concurrent software.
geronimo | The core Geronimo server modules binaries and configurations.
geronimo-spec | Legacy 1.0 Geronimo J2EE specification libraries - only the CORBA library remains here in 1.1. See org/apache/Geronimo/specs below.
howl | Highspeed Object Web Logger (HOWL), used in Geronimo to support transaction.
jdom | Java DOM support.
juddi | Scout jUDDI implementation.
junit | Junit unit testing framework.
log4j | log4j de facto standard logging API.
mx4j | MX4J; an Open Source JMX implementation.
openejb | OpenEJB, the business tier container for Geronimo.
org/apache/derby | Apache Derby, the full-featured, 100 percent Java RDBMS. Included as the built-in RDBMS of Geronimo.
org/apache/Pluto | Apache Pluto, the portlet framework for creating dynamic portal; used primarily by the Web console.
org/apache/geronimo/specs | Contains standard J2EE specification API libraries.
portlet-api | Standard API for portlets.
scout | Apache Scout jUUDI library.
stax | Stax lightweight SOAP stack.
tomcat | Binaries and library for the Tomcat Web-tier container.
tranql | Flexible data persistence layer used internally by Geronimo to handle EJB CMP and also JCA 1.5 JDBC connections.
wsdl4j | Binaries and library for Web Services Definition Language (WSDL) parser.
xerces | Full-fledged XML parser and XSLT processor.
xmlbeans | Library for working processing XML files.
xpp3 | Small, fast, and efficient XML parser that implements the XmlPull API.
xstream | XML serialization library used to serialize objects to and from XML representations.

Note that if you have a custom assembly (meaning that the server components making up Geronimo have been modified), you are likely to see a different set of directories in the repository.

The list of artifacts in the repository is reflective of the breadth of Geronimo. Some of the libraries are the servers in the default assembly; others are libraries that these servers depend on.

The Repository As a Configuration Store

You are likely to find most Geronimo system modules deployed in the server with the groupid = geronimo. Because of this, you will find most configuration information (CAR artifact) stored under the Geronimo subdirectory.

CAR artifacts are used to store the configuration state information from the installed and deployed modules. This collection of persisted CAR artifacts is sometimes referred to as the Geronimo configuration store.

The information is stored in an implementation-specific binary format. Although it is possible to figure out exactly how Geronimo stores this configuration information, you are strongly discouraged by the designers from modifying any of the files stored in a CAR artifact. In addition, this format can frequently change. In fact, during Geronimo’s very young life thus far, the organization of the configuration store has already changed dramatically between 1.0 and 1.1.

You should always use the deployer tool (or the Web console) in conjunction with the appropriate J2EE deployment descriptor or deployment plans to add, remove, or modify modules’ configuration parameters- and not alter the configuration store directly.

Understanding a CAR (Configuration Archive)

To understand how Geronimo stores module configuration information, take the example of the Tomcat server module. This system module is installed and started by the default Tomcat-based server (look for the Jetty server component if you have installed the Jetty version). The coordinates for this application, as a deployable Geronimo module, are:

  • group id = geronimo

  • artifact id = tomcat

  • version = 1.1

  • type = car

If you look under the following directory, you will indeed find the expected webconsole-tomcat-1.1.car. However, the car is not an archive file but actually a directory.

repository/geronimo/ tomcat/1.1

Underneath this CAR directory, you will actually find directories that contains the unachieved configuration and resources from your module.

The most interesting files under the CAR artifact’s subdirectory are its META-INF/ subdirectory.

Table 5-7 provides a brief description of some of the files you will find in this directory.

Table 5-7: Configuration Files under the META-INF Directory of a CAR Artifact Open table as spreadsheet
File name | Description
config.info | An information file describing the serialized configuration of a module, including the module ID, the type of component (for example, service), and a unique timestamp of serialization.
config.ser | This is the serialized version of the configuration information in a deployment plan. The Geronimo server can load modules configured in this format significantly faster than parsing XML and loading individual GBeans all over again.
config.ser.sha1 | A hash of the serialized configuration, used to verify the integrity of the serialized configuration.

The Geronimo 1.0 configuration store is separate from the repository, and consists of a hierarchy of directories combined with an external index. The 1.0 configuration store has been made obsolete by the 1.1 repository.

The config.ser file is the serialized configuration. When the Geronimo kernel starts or restarts, it only has to load these serialized configuration files to get up and running. This provides Geronimo with the following:

  • You experience very quick start and restart time, avoiding the tedious and time-consuming XML parsing necessary to analyze configuration plans.

  • You pay the penalty of configuration building upfront once only, at module deployment time. This means that any error in module configuration will be caught during deployment, and the interaction with the user is handled there. Once a module configuration is serialized, there is no need to further validate it before running.

  • You have the capability to transfer configured modules between physical processing resources (such as servers in a cluster, or computing modules in a massively parallel configuration).

Figure 5-3 show how Geronimo manages configurations.

Image from book
Figure 5-3: Configuration management in Geronimo

In Figure 5-3, the Geronimo server has three configured modules running. These modules are Module A, Module B, and Module C, respectively. In the configuration store, Geronimo maintains serialized images of each of these configurations. Specifically, Module A is stored in the numeric my/a/1.1/ a-1.1.car, Module B in my/b/1.1/b-1.1.car, and Module C in my/c/1.1/c-1.1.car directory. Each of the persisted configuration information can be retrieved easily from the repository once the module ID of the module is known.

If the server is ever interrupted or restarted, the configured module can be readily loaded from the serialized images of the configuration.

When the Geronimo kernel starts up, it must know which of the configurations in the configuration store to load. It finds out by checking the var/config/config.xml file. You will learn more about this file in the section “The var D irectory” later in this chapter.

As you deploy more components to Geronimo, the number of persisted module configurations managed by Geronimo grows. The Geronimo repository is designed to handle this with ease by mapping them into a hierarchy of directories. Of course, each time you undeploy an application or module, its persisted module configuration is removed from the repository. Note, however, that you can stop a component - in which case, it will not run when the server starts up, but the persisted module configuration information still stays in the repository.

Important

Once you’ve figured out how the configuration storage portion of the repository in Geronimo works, it is tempting to create some useful scripts to manipulate and/or save the stored information. Don’t do it. Future Geronimo implementation may change the way things work for storing the configuration (again!). In general, it is unwise to create utility or script files based on the details of the configuration storage implementation.

Storing Deployed Modules Associated with a Configuration

Now that you know Geronimo stores all the persisted module configuration information in the repository in serialized format, you may be wondering where the actual binary code of the deployed module is stored. In fact, it is also stored in the configuration store.

More specifically, it is stored immediately below the artifact’s CAR directory. Each archive file in the module is expanded and placed into directories with the same name. Figure 5-4 illustrates the configuration store after you have successfully deployed progeron.ear in Chapter 2. Recall that the progeron.ear is an application that contains the Web-tier components in progeron.war and business-tier EJB components in progeron-ejbs.jar.

Image from book
Figure 5-4: Storing deployed modules binaries within the repository

In Figure 5-4, you can see that the progeron-ejbs.jar application archive is kept intact while the progeron.war is expanded by Geronimo in the progeron.war directory. In general, the executable code archives of a module is stored either intact, or expanded in their own directories (with matching name), while the serialized configuration is always stored under in the META-INF directory.

The schema Directory

The deployment descriptor and deployment plans, used exclusively throughout Geronimo to configure components, are all XML files.

XML files are great for configuration because they are very easily parsed, validated, and processed by computer programs. Specifically, an XML schema describes to the parsing program what is allowed in a specific deployment descriptor or plan. Essentially, an XML schema describes the grammar allowed in a specific deployment descriptor or plan. It is in this directory that the schemas used by Geronimo and all of its component servers are kept.

Table 5-8 gives a brief description of each of the schema or Document Type Definition (DTD) files you will find in the default release 1.1 distribution. DTD is an older validation mechanism. DTD is less expressive than schemas and provides weaker validation of document syntax.

Table 5-8: Content of the schemas Directory Open table as spreadsheet
XML DTD or Schema | Description
application-client_1_2.dtd | DTD for client.xml used in J2EE 1.2 client JAR files deployable to the client application container.
application-client_1_3.dtd | DTD for client.xml used in J2EE 1.3 client JAR files deployable to the client application container.
application-client_1_4.xsd | Schema for client.xml used in J2EE 1.4 client JAR files deployable to the client application container.
application_1_2.dtd | DTD for application.xml used in J2EE 1.2 EAR bundles.
application_1_3.dtd | DTD for application.xml used in J2EE 1.3 EAR bundles.
application_1_4.xsd | Schema for application.xml used in J2EE 1.4 EAR bundles.
connector_1_0.dtd | DTD for JCA 1.0 resource adapters, standard J2EE deployment descriptor.
connector_1_0.xsd | Schema for JCA 1.0 resource adapters, standard J2EE deployment descriptor.
connector_1_5.xsd | Schema for JCA 1.5 resource adapters, standard J2EE deployment descriptor.
corba-css-config-2.0.xsd | Schema for CORBA CSIv2 security support. This is the schema for client-side Client Security Service (CSS).
corba-tss-config-2.0.xsd | Schema for CORBA CSIv2 security support. This is the schema for server-side Target Security Service (TSS).
ejb-jar_1_1.dtd | DTD for ejb-jar.xml used in creating EJB 1.1–compatible EJB JAR bundles.
ejb-jar_2_0.dtd | DTD for ejb-jar.xml used in creating EJB 2.0 compatible EJB JAR bundles.
ejb-jar_2_1.xsd | Schema for ejb-jar.xml used in creating EJB 3.0–compatible EJB JAR bundles.
geronimo-application-1.X.xsd | Schema for Geronimo-specific deployment plan atthe EAR level.
geronimo-application-client-1.X.xsd | Schema for the Geronimo-specific application client deployment plan.
geronimo-config-1.X.xsd | Schema for common elements in Geronimo deployment plans.
geronimo-connector-1.X.xsd | Schema for deployment plans for JCA 1.5 connectors.
geronimo-javabean-xmlattribute-1.X.xsd | Schema for JavaBean XML attributes (properties).
geronimo-jetty-1.X.xsd | Schema for a Web application deployment descriptor for use in Jetty. (Only available when the Jetty version of Geronimo is installed.)
geronimo-jetty-config-1.X.xsd | Schema for Jetty configuration of virtual hosts. (Only available when the Jetty version of Geronimo is installed.)
geronimo-login-config-1.X.xsd | Schema for definition of login modules and security realms.
geronimo-module-1.X.xsd | Schema for definition of modules, environments, and dependencies within Geronimo deployment plans.
geronimo-naming-1.X.xsd | Schema for common naming reference elements used by other Geronimo schemas.
geronimo-security-1.X.xsd | Schema for the security element used in Geronimo deployment plans.
geronimo-service-1.X.xsd | Schema for GBean-based service and dependencies in Geronimo.
geronimo-tomcat-1.X.xsd | Schema for Tomcat-specific elements that can be used when deploying applications to Tomcat. (Only available when Tomcat version of Geronimo is installed.)
geronimo-tomcat-config-1.X.xsd | Schema for Tomcat-specific configuration. (Only available when Tomcat version of Geronimo is installed.)
geronimo-web-1.X.xsd | Schema for Geronimo-specific Web-tier deployment plan.
j2ee_1_4.xsd | Sharable common descriptor elements in standard J2EE deployment descriptors.
j2ee_jaxrpc_mapping_1_1.xsd | Standard J2EE support schema to map Java language types to WSDL for Web services.
j2ee_web_services_1_1.xsd | Standard J2EE support schema to describe a Web service deployed on a J2EE server.
j2ee_web_services_client_1_1.xsd | Standard J2EE support schema.
jsp_2_0.xsd | Schema for JSP 2.0 XML syntax.
openejb-jar-2.1.xsd | Schema for openejb-jar.xml file. This is the Geronimo-specific deployment plan for EJBs.
openejb-pkgen-2.0.xsd | Schema for OpenEJB public key generation.
web-app_2_2.dtd | DTD for Web application deployment descriptor, web.xml for Servlet API 2.2.
web-app_2_3. dtd | DTD for Web application deployment descriptor, web.xml, for Servlet API 2.3.
web-app_2_4.xsd | Schema for Web application deployment descriptor, web.xml, for Servlet API 2.4.
web-jsptaglibrary_1_2.dtd | DTD for JSP Standard Tag Library (JSTL) 1.2.
web-jsptaglibrary_2_0.xsd | Schema for JSTL 2.0.
wsdl.xsd | Schema for WSDL.
xml.xsd | Schema for XML namespace.

If you are using a custom assembly of Geronimo, since the component servers may change, you may see a slightly different set of schemas in this directory. For example, if you have installed the Tomcat minimal server configuration (Little-G), you will see significantly fewer files in this directory.

Geronimo is backward compatible with J2EE 1.3 components. J2EE 1.3 made use of a different mechanism to validate XML deployment plans. The older validation mechanism is called Document Type Definition (DTD). DTDs are considerably less expressive than schemas and provide weaker validation. In addition to schema files, you will find the backward-compatible DTD files in the schema directory.

In general, you can observe that Geronimo supports J2EE 1.3 backward compatibility. XML-based configuration files are specified DTD in J2EE 1.3, while J2EE 1.4 has moved to use XML schemas instead. XML schemas are significantly more effective for validating XML configuration files.

For those readers who can read an XML schema, these files are the authoritative source to check the exact allowed syntax for any Geronimo configuration file. They are the exact schemas and DTD used by the Geronimo server to validate the associated XML descriptor file.

The var Directory

This subdirectoy contains many of the run-time dynamic contents of Geronimo. For example, the logs and the temporary work directory for run-time-generated code are kept in this directory.

Table 5-9 describes some of the subdirectories that you find here and their contents.

Table 5-9: The var Working Directories Open table as spreadsheet
Subdirectory | Description
activemq | Temporary working files for ActiveMQ.
catalina | Temporary working directories for Tomcat.
config | Geronimo configuration directory. Contains config.xml.
derby | Working directories for the Apache Derby RDBMS.
log | Directories for Geronimo and its components to save logs.
shared | Shared libraries directory for Jetty and Tomcat servers. This location can be modified by modifying the classDirs and libDirs attributes of the geronimo/sharedlib/1.x/car module in config.xml.
tmp | Temporary IO (input/output) directory for the Java Virtual Machine (JVM) that runs the Geronimo server. Location is set in the geronimo.sh (or geronimo.bat) script, via the java.io.tmpdir system property.
security | Working directories for Geronimo’s security implementation.
txlog | Transaction log subdirectory for Geronimo.

Of the subdirectories described in Table 5-9, the catalina, config, derby, log, and security directories deserve further examination.

The catalina Tomcat Working Directory

If you have worked with Tomcat 5.x before, you will recognize the content of the catalina directory. You will not see this directory if you have selected the Jetty-based download.

Basically, the Tomcat integrated into Geronimo will use the subdirectories here to store all its working files. Among others, you will find the following subdirectories:

  • ROOT - The root context directory for the Tomcat server

  • conf - Contains the default web.xml for Web applications running in Tomcat

  • logs - Location where Tomcat will place its access logs

  • work - Temporary working directory for Tomcat

Note that the server.xml file used to configure Tomcat is not located in the conf subdirectory. You must modify the configuration deployment plan for the Tomcat server to make system-level changes to the Tomcat server (such as adding valves).

See Chapter 11 for more information on Geronimo’s Tomcat configuration.

The config Directory

The config directory contains the config.xml file. This configuration file is processed by the server during Geronimo server startup. The config.xml file serves two purposes:

  • Lists the modules in the order that will be started when the server starts up

  • Allows administrators to easily modify the configuration of modules, by changing the values of GBean attributes during the startup process

Installed Modules and Startup Order

First, the general structure of the config.xml file is:

<attributes xmlns="http://geronimo.apache.org/xml/ns/attributes-1.1">
    <module name="module name">
        <gbean name="gbean name">
            <attribute name="attribute name">attribute value</attribute>
        </gbean>
            <gbean name="...">
              ...
            </gbean>
              ...
    </module>
    <module>
          ...
         </module>
         ...
</attributes>

The root element is an <attributes> element. Within the <attributes> element are one or more <module> elements. Within each <module> element are one or more <gbean> elements. And within each <gbean> element are one or more <attribute> elements that provides the attribute name to over-ride, and the value that it should be overridden to. By specifying the module name, gbean name, and attribute name, the configuration of a module started up by the server can be changed.

Each module named in this file is an installed module on the Geronimo server instance. The order in which they are listed in this file is the order in which the Geronimo server will load and start these modules when the server starts up.

Preventing Installed Modules from Starting

Not every installed module must be loaded and started when the server starts. Modules that should not be loaded should have its load XML attribute, on the <module> element, set to False. For example, to avoid loading the JavaMail transport support module, the module may be specified as follows:

<module name="geronimo/javamail/1.1/car" load="false"/>

In fact, when you use the Web console or the deploy tool to stop a module, this is exactly what the Geronimo server will do: Set the load attribute of the <module> element to “false.” Since the Geronimo server must write to the config.xml file to change its content, it must be ensured exclusive access to the config.xml file while the server is running. Therefore, it is of paramount importance that you do not write to the config.xml file while the server is running.

Only modify config.xml file when the Geronimo server is not running.

In addition, when the Geronimo server reads in the config.xml file, it does not track or maintain comments that may be original file. As a result, any comments in the config.xml file will be lost. If you absolutely need to put comments in the config.xml file, ensure that you always make a copy of it at some other location.

Changing Module Configuration by Overriding GBean Attributes

When you examine the config.xml file that comes with Geronimo, you will see many <attribute> elements inside <GBean> elements, within <modules> elements that you can change.

They are appropriately named to identify the actual module configuration value that may be modified.

For example, the Tomcat server module has the following highlighted attributes that may be modified.

<module name="geronimo/tomcat/1.1/car">
   <gbean name="TomcatEngine">
     <reference name="TomcatValveChain"/>
   </gbean>
   <gbean load="false" name="FirstValve"/>
   <gbean name="TomcatResources"/>
   <gbean name="TomcatWebConnector">
     <attribute name="host">0.0.0.0</attribute>
     <attribute name="port">8080</attribute>
     <attribute name="redirectPort">8443</attribute>
   </gbean>
   <gbean name="TomcatAJPConnector">
     <attribute name="host">0.0.0.0</attribute>
     <attribute name="port">8009</attribute>
     <attribute name="redirectPort">8443</attribute>
   </gbean>
   <gbean name="TomcatWebSSLConnector">
     <attribute name="host">0.0.0.0</attribute>
     <attribute name="port">8443</attribute>
   </gbean>
   <gbean name="geronimo/tomcat/1.1/car?ServiceModule=geronimo/tomcat/
.1/car,j2eeType=GBean,name=TomcatWebContainer">
     <attribute name="catalinaHome">var/catalina</attribute>
   </gbean>
 </module>

The first set of attributes allows you to modify the network address (if you have more than one network card on your system, use this to select the network card to use), the TCP port, and the redirect port for the Web HTTP connector. The second set can be used to change the port used by the AJP connector - for connecting to external Web servers such as the Apache Web Server. The third highlighted set can be modified for the SSL connector. The last configurable attribute sets the location of CATALINA_HOME directory, used by the Tomcat server to find the ROOT and working directory tree.

Attributes for configuration of other module are also available in the config.xml. Just remember that if a module has a load="false" attribute, it will not be started, and modifying any GBean attribute will not have any effect.

You should only modify config.xml when the Geronimo server is not running. The file is only scanned once during server startup. This means that any changes that you make to config.xml will only be effective with the next server reboot.

The Derby Database Directory

Users who are familiar with Derby or IBM Cloudscape should recognize the content of this directory. The log file for the database is located in derby.log, while each subdirectory represents a separate Derby relational database instance. The data for each database instance is stored in a subdirectory underneath the derby directory. By default, you will see the system database instance (used internally by Geronimo) located in the SystemDatabase subdirectory.

The Log Directory

This is where most server components in Geronimo will be logging in to. You will also find the logging properties file to configure logging for the various server components in this log directory. Both the level of logging (from fatal - sparse to info - verbose), as well as the location to log to (console, file, and so on), can be controlled through these log properties files.

Some of the more common log files you will encounter in this directory include the following:

  • geronimo.log - General Geronimo server log. Some components may also log within this file.

  • deployer.log - The log for the run-time deployer command-line tool.

  • client.log - The log for the Geronimo client application container.

  • jetty_XXX.log - The log created by the Jetty Web-tier component.

Note that the Tomcat Web-tier container does not log in to this directory by default. Instead, it logs to its own log directory under the catalina/logs directory.

The Geronimo Security Directory

In this security directory, you will find the property files used by the various properties file-based security realm instances in Geronimo. This default security realm looks into the users.properties file and uses entries in this file.

The following is the only line in users.properties:

system=manager

This is the security realm used by the run-time deployer and is precisely why you need to use --user system and --password manager command-line options to access it.

Other files you will find in this directory include SSL keystore and other security properties files for demonstration applications.

For more information on security realms and Geronimo’s security implementation, see Chapter 15.


Summary

You have explored the architecture of Geronimo in this chapter. Geronimo consists of a small kernel that supplies GBean components with configuration management, manageability, and lifecycle management services.

A related group of GBeans configured together is called a module. Modules are defined and configured in Geronimo using deployment plans.

The personality of a Geronimo server is determined by the set of modules that are assembled together to create the base server. This set of modules is called an assembly. The default personality of the Geronimo binary distribution is a J2EE server personality. It is possible to modify and rebuild a custom assembly for your own purposes. Chapter 18 (a bonus downloadable chapter available at www.progeronimo.com) describes the procedure.

All the directories included in the full J2EE server distribution of Geronimo 1.1 distribution have been explored in this chapter. Among other directories, you have discovered the following:

  • The repository where the component servers (and their dependent libraries) are kept. This is also the location where Geronimo maintains its configuration store - keeping a persistent image of the configurations of installed and deployed modules.

  • The doc directory.

  • The lib directory where Geronimo maintains the library APIs that it needs to start the server.

  • The var directory where server modules place working files. The config.xml file in the config subdirectory can be used to modify modules’ configuration between Geronimo server startups.

  • The schema directory where the XML schemas for all of Geronimo’s deployment plans and standard J2EE deployment descriptors reside.

You now have sufficient conceptual background to start production work with Geronimo. Chapter 6 begins tool coverage, and subsequent chapters will provide a cookbook approach to configuring different modules for the Geronimo server.


Chapter 6: The Geronimo Deployer

Overview

One of the most frequently used tools by administrators, deployers, and developers is the Geronimo command-line deployment tool. This tool is the primary means of getting binary modules installed on a Geronimo server for server-side execution.

The Geronimo command-line deployment tool can work in one of two modes:

  • Online deployment when a target Geronimo server is running

  • Offline deployment when a target Geronimo server is not running

In addition to module deployment, the tool can also be used to:

  • Start a module running

  • Stop a running module

  • View the modules that are installed on the server instance

  • Uninstall a module from a server instance

  • Find and install plug-ins for Geronimo

This chapter provides a detailed overview of the operation and usage of this essential Geronimo tool.

You will discover that the command-line deployer is actually a JSR-88 deployment client tool. This enables it to be used with servers other than Geronimo by replacing the default server driver.

A very useful component related to the run-time deployer, called the Maven deployment plug-in, will also be covered in this chapter. The Maven deployment plug-in allows you to write scripts that work with the run-time deployer mechanism in Geronimo, providing a means to automate common deployment-related tasks.


Getting Acquainted with the Deployer

You will find the binary of the deployer in the bin directory of your Geronimo distribution. The code is contained in a single JAR file:

deployer.jar

To run the deployer, you can issue the following command from the Geronimo installation directory:

java –jar bin/deployer.jar  <options> <command>  <command options>

The deployer.jar file contains only the client portion of the deployer implementation. During regular operations, it will connect to a Geronimo server instance and use the server portion of the online deployer to carry out its work. The module that must be running on the server to enable run-time deployment is called geronimo/online-deployer/1.1/car. This configuration is started by default when you start a Geronimo server instance. This configuration is the server-side mechanism that enables you to deploy modules to a server instance. In addition to online-deployment, offline deployment (essentially installation) to the local host is supported by the deployer without the need for an instance of the server running.

With Geronimo1.1, the online deployer (geronimo/online-deployer/1.1/car module) delegates to other deployer modules to do the actual deployment. The selection of deployer depends on the type of module being deployed. For a J2EE server, you must ensure that the following deployer modules are running:

  • geronimo/j2ee-deployer/1.1/car

  • geronimo/axis-deployer/1.1/car

  • geronimo/client-deployer/1.1/car

  • geronimo/openejb-deployer/1.1/car

  • geronimo/tomcat-deployer/1.1/car or geronimo/jetty-deployer/1.1/car

  • geronimo/geronimo-gbean-deployer/1.1/car

If you look in the bin directory of the distribution, you will find a deploy.bat (or deploy.sh for *nix) script for starting the deployer. You may use this script instead of invoking the self-contained JAR directory. Following is the syntax for this script file:

deploy  <options> <command>  <command options>

Deploying Modules to a Geronimo Server Instance

Some typical modules that you may deploy to Geronimo via the command-line deployment tool include the following:

  • Servlets and JSPs in the Web-tier via a WAR file

  • EJB JAR files

  • Complete multi-tier enterprise application combining WARs, EJB JAR files, and other resources

  • J2EE Connector Architecture (JCA) connectors and resources

  • Client applications using the Geronimo client application container

In each of these scenarios, the action of deploying a module involves the file transfer of the archive into the repository, parsing the deployment descriptors and deployment plans, and configuring the components (GBeans) on the server.

You deploy a module to Geronimo by supplying the following:

  • A binary code archive (JAR, WAR, EAR, and so on)

  • A deployment plan

Depending on your situation, you may supply only a binary archive, only a deployment plan, or both a binary and a deployment plan.

You supply a binary code archive only when the default J2EE deployment descriptor, embedded as a part of the archive, is sufficient for the deployment of the archive. In addition, Geronimo-specific deployment plans may also be embedded into the archive. You may want to embed Geronimo-specific deployment plans into the archive for convenience of deployment, especially in situations where the need to customize the plans is minimal. For example, deploying progeron.ear in Chapter 2 is as simple as the following:

deploy --user system --password  manager progeron.ear

Typically, you supply both a binary archive and a Geronimo-specific deployment plan when you want to control the deployment with a custom deployment plan. This can be useful when the same archive is often deployed in different scenarios. If the same type of plan is already embedded into the archive, the externally supplied plan will always override the embedded plan. This technique enables you to flexibly deploy the same binary archive in different situations. For example, if you need to deploy the progeron.ear archive with your own customized deployment plan, you can use the following:

deploy --user system --password manager progeron.ear  mycustom.xml

You supply only a deployment plan for deployment in the case where you are configuring an archive that is already in the repository. This occurs when you are either deploying a previously deployed archive or customizing a system module. A frequently occurring example is the deployment of a new Derby RDBMS database pool (JCA 1.5 connector). Since the archive of Derby database pool connector is already distributed with Geronimo (and already stored in the repository), there is no need to explicitly deploy any archive again. For example, to deploy a database pool with your own deployment plan, you may use the following:

deploy --user system --manager deploy  mydbpool.xml

The JSR-88 Personality of the Command-Line Deployer

Figure 6-1 shows the core operation of the Geronimo deployer. In Figure 6-1, you can see that the deployer deploys modules to Geronimo server(s). The deployable module can optionally be accompanied by a Geronimo-specific deployment plan.

Image from book
Figure 6-1: Geronimo run-time deployer

Ideally, the deployer can be used to deploy modules to one or more Geronimo servers known as targets. Figure 6-1 shows the possibility of deploying to multiple Geronimo servers at once. This capability is very useful, for example, in configurations where a cluster of Geronimo servers may be running.

The run-time deployer is actually coded to the JSR-88 (J2EE Application Deployment) standard. As a JSR-88 deployment tool, it is capable of working with any other JSR-88-compliant servers, simply by switching drivers. In the language of the JSR-88 specification, each of these servers is known as a target. It is anticipated that all JSR-88-compliant servers will supply such a driver to be used by deployer clients. This means that the Geronimo run-time deployer may be used to deploy modules to other non-Geronimo servers. Figure 6-1 shows this possibility - deploying to a non-Geronimo target(s).

Note that JSR-88 has configuration features that are currently not implemented by the Geronimo command-line deployer. These features may be added to the deployer in future releases.

The Benefits of JSR-88

One of the key benefits of JSR-88 is the concrete specification of a set of deployment APIs, allowing any deployment client to work with any compliant server.

Other than the possibility of using the Geronimo command-line deployer with other JSR-88 servers (which is rather uninteresting for Geronimo users) is the possibility of using other clients with the Geronimo server. Figure 6-2 illustrates the JSR-88 plug-in capability.

Image from book
Figure 6-2: The interoperable JSR-88-compliant components

In Figure 6-2, the Geronimo command-line deployer is shown connected via a JSR-88 driver. Using this approach, the deployer can be used for any JSR-88-compliant server - and not restricted to Geronimo alone.

The second scenario shown in Figure 6-2 allows modules to be deployed to Geronimo by any JSR-88-compliant client. Imagine an IDE with a built-in JSR-88 client (most IDEs nowadays include a built-in JSR-88 client). It would be able to deploy modules to Geronimo by simply adding the Geronimo JSR-88 driver.

Support for Offline Installation Mode

The Geronimo deployer supports offline installation. In this offline mode, a Geronimo server instance is not running on the local host machine. Figure 6-3 contrasts the “regular” online deployment mode and the special offline mode of operations.

Image from book
Figure 6-3: Online deployment versus offline installation

In Figure 6-3, you can see that the deployer collaborates with a running server instance to install and start a module when operating in the online mode. When operating in offline mode however, the repository of the server being deployed to must be local. In this case, the deployer actually deploys to the local repository directly - without the assistance of a server-side implementation.

You can use the offline deployer functionality whenever the following occurs:

  • The Geronimo server is not running on the local host.

  • You use the deployer with the -offline switch during deployment.

For example, if you needed to deploy progeron.ear archive to the local server while the server is not running, you would use the following command:

deploy --user system --password manager -offline deploy progeron.ear


Using the Deployer

The following is the generalized syntax of the command-line run-time deployer command:

deployer [general options]  command  [command options]

The items enclosed in brackets are optional. You may specify one or more of them, or just leave them out.

If you are using the deploy.jar file directly, not using one of the scripts (deploy.bat or deploy.sh), the generalized command is:

java -jar deploy.jar [general options]  command  [command options]

The following sections will examine each of available general options, commands, and command options.

Deployer General Options

The general options allow you to control the environment that the deployer will execute under. Table 6-1 describes the allowable general options.

Table 6-1: General Options for Command-Line Deployer Open table as spreadsheet
Option | Description
--uri <URI to Geronimo server> | Specifies a URI for connect to a Geronimo server. By default, the deployer will connect to the server on the local host at TCP port 1099. Deploying to a remote server is possible by specifying a hostname (or IP address) and a TCP port number. The general format of the URI is deployer:geronimo: jmx:rmi:///jndi/rmi:[//host[:port]]/JMX Connector
--host | Another way to specify the host (or IP address) of the server that you are deploying to. The default is localhost.
--port | Another way to specify the TCP port of the server that you are deploying to. The default port value is 1099.
--driver <path to driver JAR file> | Allows you to use the deployer with other JSR-88-compatible servers. Ideally, this tool can work with other non-Geronimo servers. In practice, this is seldom used.
--user <user id> | Specifies the username for authentication to the Geronimo server. Use the --password option to specify the password. Most deployer commands require authentication. If you forget to specify this option, the deployer will prompt you for a user ID.
--password <password> | This is always used in conjunction with --user. Specifies the password associated with the specified username when authenticating to the Geronimo server. If you do not supply the password, the deployer will prompt you interactively for the password on the command line.
--syserr [ true | false ] | Instructs the deployer to log errors to syserr device. This is usually the console unless redirected. Default is false.
--verbose [ true | false ] | Turns verbose execution on or off. Default is false. Turning this on will give more information during deployment. Can be useful when debugging your deployments.
--offline | Use the offline deployer to deploy the module. As its name implies, the offline deployer allows you to deploy to the local repository without having an instance of the Geronimo server running.

Deployer Commands

There are several available deployer commands. These commands can be readily grouped as follows:

  • Commands that work with modules

  • Commands that provide information

  • Commands that work with Geronimo plug-ins

The following sections examine each of these groups in order.

Commands That Work with Modules

First, commands that work with modules are shown in Table 6-2.

Table 6-2: Commands That Work with Modules Open table as spreadsheet
Command | Description
deploy | Deploy a module to the target server(s). A module can be an EAR, JAR, WAR, and so on. Internally, the module configuration is serialized to the repository by Geronimo. In addition, the var/config/config.xml file will be updated to include the module in the modules list. The deploy command will also start the module running. When this command is used with the offline deployer option (--offline), the module is marked to start the next time Geronimo starts up (via the var/config/config.xml file).
start | Start a stopped module running.
stop | Stop a running module.
undeploy | Remove and delete a previously deployed module from the repository, stopping it first if it is running.
redeploy | This is a shortcut command that combines an undeploy operation, immediately followed by a deploy on the specified module. This is useful when you are upgrading a deployed module.
distribute | Install a module without starting it. The operation performs the exactly sequence of steps as the deploy command, except the resulting module is not started by default. This also means that the module is added to the var/config/config.xml file with a load="false" attribute.
login | Save your user ID and password information to a file in your home directory (\Documents and Settings\<username> in Windows, and usually ~/<username> in *nix). The file is named .geron-imo-deployer. If you connect to multiple servers, Geronimo will save each of your user ID and password for each server. If you save the user ID and password, future deployer invocation will not require the --user and --password options.

Each of the commands shown in Table 6-2 may be executed even if the corresponding server is not running (offline mode) by specifying the --offline option

In the offline mode, starting and stopping of modules cannot occur. However, the corresponding configuration will be marked so that it will either run (or not run) the next time the server is started. This is done by adding the module to the var/config/config.xml and setting the load attribute appropriately. Again, this offline mode of operation is only supported when the Geronimo module to be started/stopped is local to the deployer (on the same physical machine).

Commands That Supply Information

Several commands of the online deployer do not manipulate any modules or the repository, but simply provide information. The commands that provide information are shown in Table 6-3, together with a description of their options where applicable.

Table 6-3: Commands That Supply Information Open table as spreadsheet
Command | Description
help | This is the general help command, very useful to get a reminder of the available commands and options. The command deploy help options will provide general help on the available options. The command deploy help <command> will provide specific help on a command, including the options that the command may take.
list-modules | List the currently deployed modules. There are command options to show only started (--started) modules or only stopped modules (--stopped). The default is to show all deployed modules (--all). You can also specify the target(s) that the deployer will query for modules. The default is to query the local host.
list-targets | List all known targets by the current server. As of release 1.1, Geronimo does not support deployment to multiple physical servers. In release 1.1, if the single server manages multiple repositories, then each repository is considered a separate target. This command does not support any of the general options.

For example, to see the help for the list-targets command, use the following command:

deploy help list-targets

To see all the modules that are in the started state, use the following:

deploy list-modules --started

To see all the modules that have been marked to start, when the Geronimo server is not running, use the following:

deploy --offline list-modules --started

Commands That Work with Geronimo Plug-Ins

Geronimo plug-ins are ready-to-use features and applications that can be easily installed over a network (or the Internet). Plug-ins are maintained in remote repositories. Chapter 17 (available on the companion Web site) explains plug-ins in more details. Two of the deployer’s commands work with plug-ins. These commands are shown in Table 6-4.

Table 6-4: Plug-In Support Command Open table as spreadsheet
Command | Description
install-plugin | This command installs a plug-in. The command option should specify a plug-in descriptor XML file. This is frequently called plugin.xml. If you have just created or downloaded a plug-in, you should have this file.
search-plugins | The command option you must specify is a URL to the remote plug-in repository. A plug-in repository is simply a Maven 2 repository with plug-in installed.

Searching and Installing Plug-Ins

For example, the command to show all the plug-ins at the publicly accessible geronimoplugins.com site is as follows:

deploy search-plugins http://www.geronimoplugins.com/repository/geronimo-1.1/

This will search the repository at geronimoplugins.com and a typical output might be as follows:

Using GERONIMO_BASE:   C:\gerbuild\geronimo-1.1
Using GERONIMO_HOME:   C:\gerbuild\geronimo-1.1
Using GERONIMO_TMPDIR: C:\gerbuild\geronimo-1.1 \var\temp
Using JRE_HOME:        C:\javabin\jdk14211
Username: system
Password:

    Security
        1 : Apache Directory 0.92 for Geronimo (1.1-SNAPSHOT)

    Core Geronimo
            Geronimo Welcome Web App (Jetty) (1.1-SNAPSHOT)
        2 : Geronimo Welcome Web App (Tomcat) (1.1-SNAPSHOT)
        3 : Geronimo Admin Console (Tomcat) (1.1-SNAPSHOT)
            Geronimo Admin Console (Jetty) (1.1-SNAPSHOT)

    Examples
            Jakarta JSP Examples (Jetty) (1.1-SNAPSHOT)
        4 : LDAP Example Security Realm (1.1-SNAPSHOT)
        5 : LDAP Example Web App (Tomcat) (1.1-SNAPSHOT)
            Jakarta Servlet Examples (Jetty) (1.1-SNAPSHOT)
        6 : Jakarta JSP Examples (Tomcat) (1.1-SNAPSHOT)
            LDAP Example Web App (Jetty) (1.1-SNAPSHOT)
        7 : Jakarta Servlet Examples (Tomcat) (1.1-SNAPSHOT)

    Resources
        8 : Oracle XA Driver for Console (Tomcat) (1.0)
            Oracle XA Driver for Console (Jetty) (1.0)

Install Service [enter number or 'q' ; to quit ]:q

This menu allows you to choose a plug-in to install interactively.

Obtaining Module Run-Time State Information

It is possible to obtain run-time state information using the deployer. The following shows the typical output from a list-modules command of the run-time deployer:

C:\gerbuild\geronimo-1.1-rc1\bin>deploy --user system --password manager list-mo
dules
Using GERONIMO_BASE:   C:\gerbuild\geronimo-1.1
Using GERONIMO_HOME:   C:\gerbuild\geronimo-1.1
Using GERONIMO_TMPDIR: C:\gerbuild\geronimo-1.1\var\temp
Using JRE_HOME:        C:\javabin\jdk14211
Found 32 modules
  + geronimo/activemq/1.1/car
  + geronimo/activemq-broker/1.1/car
  + geronimo/axis/1.1/car
  + geronimo/axis-deployer/1.1/car
  + geronimo/client-deployer/1.1/car
  + geronimo/geronimo-gbean-deployer/1.1/car
  + geronimo/hot-deployer/1.1/car
  + geronimo/j2ee-deployer/1.1/car
  + geronimo/j2ee-security/1.1/car
  + geronimo/j2ee-server/1.1/car
  + geronimo/j2ee-system/1.1/car
  + geronimo/openejb/1.1/car
  + geronimo/openejb-deployer/1.1/car
  + geronimo/remote-deploy-tomcat/1.1/car @ http://your-e7427193eb:8080/remo
te-deploy
  + geronimo/rmi-naming/1.1/car
  + geronimo/sharedlib/1.1/car
  + geronimo/system-database/1.1/car
  + geronimo/tomcat/1.1/car
  + geronimo/tomcat-deployer/1.1/car
  + geronimo/webconsole-tomcat/1.1/car
      `-> standard.war @ http://your-e7427193eb:8080/console-standard
      `-> framework.war @ http://your-e7427193eb:8080/console
  + geronimo/welcome-tomcat/1.1/car @ http://your-e7427193eb:8080/     geronimo/client/1.1/car
    geronimo/client-corba/1.1/car
    geronimo/client-security/1.1/car
    geronimo/client-system/1.1/car
    geronimo/j2ee-corba/1.1/car
    geronimo/javamail/1.1/car
    geronimo/online-deployer/1.1/car
    geronimo/shutdown/1.1/car
    geronimo/uddi-tomcat/1.1/car
    geronimo/upgrade/1.1/car
    geronimo/upgrade-cli/1.1/car

Note in this listing that some modules listed are marked with a leading “+” sign, while others are not. Every one of the modules marked with a leading “+” is started and in the running state. Any listed module that does not have a leading “+” is in the repository but has not been started.

There is an alternative way to obtain this run-time state information via the Geronimo Web console. Using the Web console, you can select one of the options in the Applications heading and see the current run-time state of installed modules of different type. Figure 6-4 shows the Web Console display of System Modules.

Image from book
Figure 6-4: Using the Web console to display module run-time state

In Figure 6-4, the actual state of each configuration is show in its own column. You can see that the geronimo/client-corba/1.1/car module is stopped, while the geronimo/tomcat/1.1/carmodule is running.

Chapter 8 provides more detail on the options available with the Web console.

The Maven Deployment Plug-In

Another very useful tool (directly related to online deployer) is the deployment plug-in designed for Maven 1.x. This plug-in takes advantage of the Geronimo deployer’s JSR-88 compliance, and enables deployment from within a Maven script.

Maven is Geronimo’s project management tool designed to work with very large projects that may include many subprojects. If you need to rebuild Geronimo (say, to create a custom assembly), you will need to install and run Maven. Using Maven, you can also script frequently performed administration tasks as Maven build goals.

If you are not already familiar with Maven, consult the official Maven documentation at the URL below:

http://maven.apache.org/maven-1.x

The official Maven Web site provides an overview, introduction, and examples for using Maven. There are two current versions of Maven: Maven 1.1 and Maven 2.0. The plug-in for Geronimo 1.1 currently works with Maven 1.x only.

The remainder of this chapter covers the Maven plug-in for Geronimo deployment. This plug-in enables you to create Maven scripts to automate some administrative tasks. A couple of cookbook-style examples will show how you may use the deployment plug-in with Maven.

Maven 1.x can be configured to find this plug-in and its associated tag libraries through two XML configuration files: project.xml and maven.xml. To allow Maven to find the plug-in, add the following <dependency> to the <dependencies> section of the project.xml file:

<dependencies>
        <dependency>
            <groupId>geronimo</groupId>
            <artifactId>geronimo-deployment-plugin</artifactId>
            <version>1..1</version>
            <type>plugin</type>
        </dependency>
        ...
       <dependency>
            ....
        </dependency>
       ....
</dependencies>

You can then add a namespace for the elements in your plug-in by adding the highlighted element of the <project> element in the maven.xml file:

<project default="default"
    xmlns:j="jelly:core"
    xmlns:u="jelly:util"
    xmlns:ant="jelly:ant"
    xmlns:define="jelly:define"
    xmlns:velocity="jelly:velocity"
    xmlns:bootstrap="geronimo:bootstrap"
    xmlns:deploy="geronimo:deploy"
    xmlns:artifact="artifact"
    xmlns:m="jelly:maven"
    >

Once you have declared the namespace, you can use the various elements available for the plug-in. Table 6-5 enumerates the available elements and describes their functions.

Table 6-5: Functional Elements Available in the Geronimo Maven Deployment Plug-In Open table as spreadsheet
Element | Description
<deploy:deploy> | Deploy a module, a module and a plan, or a plan to the specified server. The specified module will be started on the server. The server is specified via a uri attribute. You can supply a username and password attribute to authenticate the user. Both the module and plan attributes are optional, but one of them must exist.
<deploy:undeploy> | Undeploy a module to the specified server. The server is specified via a uri attribute. The module will be removed from the repository and the server instance’s var/config/config.xml file.
<deploy:distribute> | Deploy a module, a module and a plan, or a plan to the specified server. The specified module will not be started on the server. Instead, it will be installed. The server is specified via a uri attribute. You can supply a username and password attribute to authenticate the user. Both the module and plan attributes are optional, but one of them must exist.
<deploy:waitForStarted> | Wait for the startup of a remote server. This element is useful when you need to synchronize with the starting of a Geronimo server.
<deploy:startRemoteServer> | Start a Geronimo server instance.
<deploy:stopRemoteServer> | Stop a Geronimo server instance.
<deploy:start> | Start a Geronimo module.
<deploy:stop> | Stop a Geronimo module.

The following sections provide you with cookbook-style Maven script segments that you can use to perform specific functions using the elements shown in Table 6-5.

Deploying a Module to a Geronimo Server and Starting It

The following script segment can be used within Maven to deploy a module to a Geronimo server and start it:

<deploy:deploy
  uri="deployer:geronimo:jmx:rmi://localhost/jndi/rmi:/JMXConnector"
  username="system"
  password="manager"
  plan="c:/myplans/mywebdeployment.xml"
  module="c:/mymodules/mywebapp.war"
  />

Note the format of the uri attribute. This is the JMX connector used by Geronimo for run-time deployment.

The plan attribute is optional, and you only need it if you have a Geronimo-specific deployment plan for the module that you are deploying.

Distributing a Module to a Geronimo Server without Running It

The following script segment can be used within Maven to distribute a module to a Geronimo server without starting it. This will install the application in the server’s repository. The application will be marked to start the next time the server is started (by modifying the config/config.xml file).

<deploy:distribute
   uri="deployer:geronimo:jmx"
   username="system"
   password="manager"
   plan="c:/myplans/mywebdeployment.xml"
   module="c:/mymodules/mywebapp.war"
   />

Note the format of the uri attribute. This is the JMX connector used by Geronimo for run-time deployment.

The plan attribute is optional, and you only need it if you have a Geronimo-specific deployment plan for the module that you are deploying.

Starting Geronimo Server Instance

You can launch an instance of a Geronimo server using a Maven script and the startRemoteServer element, as shown here:

<deploy:startRemoteServer
   geronimoTarget="c:/gerbuild/geronimo-1.1"
   vmArgs="-Xmx512m ...
/>

To ensure that the server starts properly, you must specify the Geronimo installation directory (on the local host) with the geronimoTarget attribute. You can then set any JVM arguments in the vmArgs attribute.

Waiting for a Geronimo Configuration to Start

It is not safe to start interacting with a server instance immediately after the preceding script is executed. This is because it takes a significant amount of time to start all the configurations for a running server instance. Because one module may depend on another, Geronimo may have to start many other modules before starting a specified module that is to run.

The following Maven script segment can be used to wait until a specific Geronimo configuration has started successfully. In the following example, the script segment will wait for the geronimo/tomcat/1.1/car, the Tomcat server module, to start. This is specified by the id attribute of the element. Note that this specific element uses a polling algorithm to determine if a configuration has started, and the maxtries attribute specifies how many times to retry if the configuration has not yet started

<deploy:waitForStarted
   uri="deployer:geronimo:jmx:rmi://localhost/jndi/rmi:/JMXConnector"
   maxtries="125"
   username="system"
   password="manager"
   id="geronimo/tomcat/1.1/car"/>

Shutting Down Geronimo Server from a Script

It is possible to shut down an instance of the Geronimo server from a Maven script. Use the following script segment to shut down the Geronimo server on the local host. You need not change the value of any of the attributes.

<deploy:stopRemoteServer
    uri="deployer:geronimo:jmx:rmi://localhost/jndi/rmi:/JMXConnector"
    username="system"
    password="manager"/>


Summary

The deployer is one of the most frequently used command-line tools for Geronimo. The deployer is used to deploy modules to a Geronimo server. A deployment plan can be optionally used to customize the deployment beyond the available options in a standard J2EE deployment descriptor.

The deployer \can work while a Geronimo server instance is running, using the online deployer on the server side. Or, the deployer can work in an offline mode locally without a Geronimo server running.

The deployer is actually a JSR-88-compliant deployment client. This means that it can use drivers from other JSR-88-complaint servers and deploy to those servers.

Geronimo’s JSR-88 support enables it to be used with other deployment clients. A deployment client can be built into an IDE (allowing that IDE to deploy to Geronimo).

The Maven deployment plug-in for Geronimo can be used within Maven scripts to automate common administration tasks.

When deployment does not work quite the way you expected, you can turn up the verbosity of the deployer’s logging via the --verbose general option. Often, however, there may be a need to see if a particular software component belonging to a module is actually loaded and running - or has failed. Chapter 7 reveals how you may obtain this finer granularity of information from a running Geronimo server.


Chapter 7: Using the Geronimo Debug Console and jconsole

Overview

When things do not work as expected, you need tools that you give you the inside information to effectively troubleshoot and resolve problems. While the deployer goes to some length to display running modules and state information, it does not currently provide detailed information on most components residing in a Geronimo server instance.

To obtain the low-level detail information on the components that comprise a Geronimo server, you will need a secret troubleshooting tool. This little known tool has existed since the very early days of Geronimo Milestone 2, and it is aptly named the Geronimo debug console. While all administrators are familiar with the graphical Web console found with Geronimo Milestone 5 release and beyond, fewer have ever heard of the debug console.

This chapter introduces you to this very useful tool, where it is located, how to start it, and, most importantly, how to use it.

The architecture of the debug console is examined. As a prerequisite, you need to understand the basis technology that the debug console is built upon, including the following:

  • Java Management Extension (JMX)

  • JSR-77 J2EE management

This chapter provides an overview of JMX, as well as how it relates to JSR-77 and Geronimo. Key concepts in JSR-77 are covered, and their relevance to the debug console is revealed.

You will get some hands-on practice troubleshooting an actual deployment. A step-by-step walkthrough of a troubleshooting session with an actual application is included. You will also:

  • Learn the steps involved in general troubleshooting

  • Understand basic log analysis

  • Be able to use the debug console to obtain low-level component information to assist you in troubleshooting

By the end of this chapter, you should be familiar with the operations of the debug console, and should be comfortable in using it to troubleshoot deployments in Geronimo.

For readers who are running Geronimo under JDK 1.5, the jconsole JMX tool (a part of the JDK) can also be used to monitor and troubleshoot Geronimo. Coverage of how to use jconsole is provided side-by-side with the Geronimo debug console discussion.


Debug Console Architecture

The Geronimo debug console provides you with direct access to the set of objects managed by the Geronimo kernel. These objects are components that make up the servers within Geronimo. You know from Chapter 5 that these components are called GBeans. For example, Tomcat is represented by such a set of GBeans in Geronimo. Other than having its lifecycle (start, stop, and so on) managed by the Geronimo container, a GBean can optionally expose other attributes or operations for management purposes.

A standard JSR exists that specifies how Java components should expose attributes, operations, and events for management purposes. This specification is JSR-3, Java Management Extensions (JMX). Geronimo’s GBeans are JMX-manageable - providing management features for any agent or management system compatible with JMX.

In fact, Geronimo was designed to be manageable from day one. As such, the container actually provides the facility to expose attributes via JMX. All a GBean has to do is define the properties (attributes) that it wants exposed. Not every GBean will have JMX-manageable attributes, however. The ability to expose these features for external management is optional. Some specialized or customized Geronimo assembly may also choose to turn off support for JMX altogether. However, the standard J2EE 1.4 certified distribution of Geronimo does support JMX, and it is through this built-in support that the debug console functions.

You will need some background on JMX and the JSR-77 specification before you can fully appreciate how the debug console can be really useful. The following two sections provide the prerequisite overview and an explanation of key concepts and terms.


JMX Overview

JMX is the subject of JSR-3. It is a specifically created by an expert group with decades of network and system-management experience. The idea was to create a model and an API that facilitates the large-scale monitoring and management of Java-based systems and components. The specification addresses software components and services, as well as embedded devices using Java internally.

JSR-3 not only covers devices and services being controlled by an external entity but also the model and API enable the creation of network-management systems or enterprise-management systems using the Java programming language. Detailed attention is paid to backward compatibility with existing devices and services, as well as existing network-management systems. JMX is compatible with (and can work concurrently with) established network-management protocols, including Simple Network Management Protocol (SNMP) and the Common Information Model (CIM).

The JMX Levels

The model described in JSR-3 consists of three distinct layers. Each of these layers is the subject of a different specification. Figure 7-1 illustrates the JMX levels.

Image from book
Figure 7-1: JMX levels

In Figure 7-1, the bottommost layer is the Instrumentation level, which is discussed next.

Instrumentation Level

The JMX model on the Instrumentation level describes how devices and software components can expose attributes and operations for management. It defines a set of standard Java interfaces that enable a manager (from the Agent level) to monitor, manage, and/or control the device or component. Management attributes are exposed by the device or component via the creation of Managed Beans (MBeans), which are JavaBeans that represent the resources being managed.

Each MBean can expose attributes for management. These attributes are equivalent to JavaBean properties; their value may be read or written to by the management agent. For example, a message queue MBean may want to expose the number of messages as an attribute. MBeans can also expose operations, which are equivalent to method invocations. For example, an MBean for a server may expose an operation named reboot to enable an agent to reboot the server. Last, but not least, MBeans can also choose to fire notification events. For example, a disk device with Java-based controller software may fire a notification if it is 80 percent full.

Even though MBeans are always accessed through components in the Agent level, they have no special knowledge of these components. The Instrumentation level is separate from, and not dependent on, the Agent-level components.

Agent Level

MBeans are aggregated at the Agent level by an MBean server. An MBean server provides the link between the MBeans and external management applications or higher-level distributed services. The MBeans themselves are not aware of interactions with external agents. Instead, the MBean server is responsible for providing the API to locate and retrieve the MBeans.

The MBean server is free to use either the MBean’s interface and expose that to the next level or choose to expose its own interface and then perform operations on the aggregated interfaces of the MBeans. As an example, an MBean server performing a cluster shutdown operation on behalf of a management application may implement the shutdown operation by iterating through the administration MBeans from every Geronimo server in a cluster and shutting it down. Figure 7-2 shows the composition of the JMX Agent level.

Image from book
Figure 7-2: JMX Agent level

By having an Agent level, the development of MBeans in the Instrumentation level can be made completely independent of the development of network management systems. This clean decoupling allows instrumentation and management tools development to proceed at their own pace. For example, all of the GBeans in a Geronimo server are instrumented for management (MBeans are available), and this is all done without the need to know what management tool may be used to access the MBeans.

Also at the Agent level is connector code that enables concurrent access to the aggregated MBeans by multiple incoming requests. Requests coming into the MBean server may actually be from different network-management applications using different network-management protocols. This will require the service of protocol adapters and converters; these protocol converting components also live at the Agent level. For example, a protocol adapter may enable a Geronimo server to be monitored and managed by an SNMP-based management system.

Last, but not least, the Agent layer also contains a well-defined set of agent services that can be used by any developers writing value-added logic at the Agent level. For example, a timer service is available for one-shot timing, and a monitoring service is available for monitoring changes to an MBean attribute.

Distributed Services Level

Distributed Services in JMX represent the highest-level networked services that communicate with the agents at the Agent level to perform network-management tasks. Typically, large network-management systems have services running on a network. For example, a distributed service may monitor a set of MBean servers for exception conditions with the MBeans that they aggregate.

The specification at the Distributed Services level will describe the API and model for creating distributed network-management applications. As of this writing, the specification for the Distributed Services level of JMX is not yet available.


JSR-77 Overview

In 2001, JSR-77 was introduced to address the issue of managing J2EE servers. While most of the deployable modules in J2EE can be created in ways that are independent of the hosting servers, it was not possible to use a generic management tool to manage different J2EE servers. This is because the management APIs of most network-management products are proprietary.

JSR-77 addresses this issue by defining a standard model (a meta-model) and a set of conventions for J2EE Management. JSR-77 is based on the JMX specification. While the JMX specification’s focus is on management of generic resources (such as hardware components, software services, and so on), the JSR-77 specification is focused on management of J2EE servers and components. This specification became final in July of 2002 (with an update in August of 2005).

Implementation of JSR-77 can lead to manageable servers that work with a variety of management tools. That is, a JSR-77 management tool or system should be able to manage any JSR-77-compliant server.

Management EJB

In the JSR-77 model, the management application communicates with and obtains management information on the server through a Management EJB (MEJB) component. The API to this MEJB is defined by JSR-77.

Through the MEJB, you can look up and access exposed management attributes, invoke exposed operations, or receive events from manageable server components. If this starts to sounds like JMX to you, you are right on the money.

In fact, the MEJB actually operates at the Agent level of functionality (with respect to the JMX model). Being a J2EE management model, the use of EJB at the Agent level is one of the natural ways of implementing JMX remote access. However, even though access through MEJB is preferred, JSR-77 also specified information for an SNMP MIB and CIM mappings to ensure backward compatibility with legacy management tools and systems. The specification does not require the support and implementation for these legacy management protocols. Specific implementations may have connectors and protocol converters at the Agent level to communicate via these legacy systems.

A JSR-77 management application can locate the MEJB in a JSR-77-compliant server (such as Geronimo) via Java Naming and Directory Interface (JNDI). The code that is typically used is shown here. It is not important that you understand this code; just note the lookup in the highlighted line.

Context ctx = new InitialContext( );
Object objref = ctx.lookup("ejb/mgmt/MEJB");
ManagementHome home = (ManagementHome)
    PortableRemoteObject.narrow(objref,ManagementHome.class);
Management mejb = home.create( );

On a JSR-77-complaint server, looking up ejb/mgmt/MEJB using JNDI will always provide the MEJB instance. In addition, any components that the MEJB returns must be valid JMX MBeans consistent with the model defined in JSR-77. Of course, the MBeans can all have exposed attributes and operations, or fire events.

Figure 7-3 shows the operations of the JSR-77 MEJB.

Image from book
Figure 7-3: Operations of an MEJB in a JSR-77 server such as Geronimo

In Figure 7-3, you can see that the JSR-77 management application (considered a client) queries the EJB for information on the server. In return, the MEJB returns JMX MBeans to the JSR-77 client application. Figure 7-3 also shows that the JMX MBeans can be from different domains. A domain is a namespace - roughly corresponding to a specific component category. Domains are specific to a JSR-77 implementation. You will see how Geronimo makes use of the domain shortly.

Meanwhile, it is important to realize that the Geronimo debug console is actually a JSR-77 client application. It makes queries into the set of Geronimo’s kernel-managed objects via the MEJB agent. Figure 7-4 shows the internal architecture of the debug console.

Image from book
Figure 7-4: Geronimo debug console is a JSR-77 client application

In Figure 7-4, you can see that the debug console actually runs as a Web-tier application inside the Geronimo server. It is a JSR-77 client application that runs within Geronimo. You interact with the debug console via a Web browser, and internally it queries the MEJB agent using JSR-77-specified APIs. The core function of the debug console is to query and report information from JMX MBeans of Geronimo kernel-managed components.

Unlike many other JSRs, JSR-77 does not mandate the inclusion of specific Java implementation classes for the server (except for the MEJB component). However, JSR-77 does have very specific requirements of how components should be named, what components must be available, and how components are related. This is spelled out explicitly in the model described by JSR-77.

One very important aspect of the JSR-77 model is the way objects are named.

Object Names in JSR-77

In the JSR-77 model, every single object is a descendent of J2EEManagedObject.

The J2EEManagedObject contains attributes that must exist on every JSR-77 object. These include the following:

  • An object name

  • A stateManageable Boolean indicating if the operational lifecycle states of the object is manageable by the container

  • A statisticsProvider Boolean indicating if the object provides statistics (through well-defined attributes in JSR-77)

  • An eventProvider Boolean indicating if the object fires an event

As Geronimo administrators, the attribute of most interest to us is the object name - since the other attributes are really meant for consumption of the JSR-77 management tool/client.

The object name is the primary means for you to get information on GBean components using the debug console. Familiarity with JSR-77 naming will help you in working with the debug console.

Each object name in JSR-77 is in the following form:

[domain name]:j2eeType=value,name=value,<parent j2eeType>[,property=value]*

This form requires some explanation. First, the domain name is optional. Then, a series of key-value pairs are specified. The order of appearance of these key-value pairs in the name is not important.

The mandatory keys are shown in Table 7-1.

Table 7-1: Mandatory Keys in the JSR-77 Object Name Open table as spreadsheet
Key | Description
j2eeType | The type of J2EE component that is represented by the object. It can be one of the following JSR-77 defined values or a container-specific value: J2EEDomain, J2EEServer, J2EEApplication, AppClient Module, EJBModule, WebModule, ResourceAdapterModule, EntityBean, StatefulSessionBean, StatelessSessionBean, MessageDrivenBean, Servlet, ResourceAdapter, JavaMail- Resource, JCAResource, JCAConnectionFactory, JCAManaged- ConnectionFactory, JDBCResource, JDBCDataSource, JDBC-Driver, JMSResource, JNDIResource, JTAResource, RMI_IIOPResource, URLResource, JVM.
name | A name for the object; the format of this name can be specific to the server. However, for j2eeType=J2EEDomain objects, the name must be the name of the domain.
<parent j2eeType> | This is actually a key-value pair in the form of <j2eeType of parent> = <name of parent object>. Depending on the j2eeType of the object, there are different mandatory <parent j2eeType> keys. See the Table 7-2 for more information.

Other than these mandatory keys, the server can also add other related property=value pairs to the name.

Table 7-2 shows the mandatory parent J2EE types that must be specified depending on the type of the object.

Table 7-2: J2EE Types of Mandatory Parent Keys Open table as spreadsheet
Type of Object | Parent j2eeType That Must Be Specified
J2EEDomain |
J2EEServer |
J2EEApplication | J2EEServer
AppClientModule | J2EEServer, J2EEApplication
EJBModule | J2EEServer, J2EEApplication
WebModule | J2EEServer, J2EEApplication
ResourceAdapterModule | J2EEServer, J2EEApplication
EntityBean | J2EEServer, J2EEApplication,EJBModule
StatefulSessionBean | J2EEServer, J2EEApplication,EJBModule
StatelessSessionBean | J2EEServer, J2EEApplication,EJBModule
MessageDrivenBean | J2EEServer, J2EEApplication, EJBModule
Servlet | J2EEServer, J2EEApplication, WebModule
ResourceAdapter | ResourceAdapterModule, J2EEServer, J2EEApplication
JavaMailResource | J2EEServer
JCAResource | ResourceAdapter, J2EEServer
JCAConnectionFactory | JCAResource, J2EEServer
JCAManagedConnectionFactory | J2EEServer
JDBCResource | J2EEServer
JDBCDataSource | JDBCResource, J2EEServer
JDBCDriver | J2EEServer
JMSResource | J2EEServer
JNDIResource | J2EEServer
JTAResource | J2EEServer
RMI_IIOPResource | J2EEServer
URLResource | J2EEServer
JVM | J2EEServer

By enforcing the explicit naming of the parent’s j2eeType, a tree of objects is specified through this naming convention. An example will make it clear why this is important. Consider that you have just deployed an enterprise application EAR file, named progeron.ear, with the following components in the archive:

  • A stateless session bean named AuthorEJB (the name as configured by an <ejb-ref> element in the deployment descriptor)

  • An EJB JAR file called progeron-ejbs.jar, which contains AuthorEJB

  • A servlet named Show authors (the name is configured by a <servlet-name> element in the deployment descriptor)

  • A WAR file called progeron.war, which contains the Show authors servlet

The JSR-77 object name for the progeron-ejbs.jar EJB JAR file is:

geronimo.server:
J2EEApplication=progeron,J2EEServer=geronimo,j2eeType=EJBModule,
name=progeron-ejbs.jar

The j2eeType for progeron-ejbs.jar is EJBModule, and the required parent j2eeTypes according to Table 7-2, are just J2EEServer and J2EEApplication.

The JSR-77 object name for the AuthorEJB session bean, contained within the progeron-ejbs.jar file, is:

geronimo.server:
EJBModule=progeron-ejbs.jar,J2EEApplication=progeron,J2EEServer=geronimo,
j2eeType=StatelessSessionBean,name=AuthorEJB

Checking against Table 7-2, the mandatory parent j2eeTypes in this case, for a StatelessSession Bean are J2EEServer, J2EEApplication, and EJBModule. Specifically, the parent EJBMoudle key contains progeron-ejbs.jar, creating a parent-child relationship between the two objects.

The JSR-77 object name for the progeron.war file is:

geronimo.server:J2EEApplication=progeron,J2EEServer=geronimo,j2eeType=WebModule,
name=progeron.war

The j2eeType of this object is WebModule, and the only parents required are J2EEServer and J2EEApplication.

The Show authors servlet, contained in progeron.war, has the following JSR-77 name:

geronimo.server:J2EEApplication=progeron,J2EEServer=geronimo,
WebModule=progeron.war,j2eeType=Servlet,name=Show authors

The j2eeType is Servlet in this case, and the WebModule - progeron.war - is named as its parent.

Armed with Table 7-2, you can locate any deployed application component by specifying its JSR-77 name. This will be very useful when you work with the debug console.

You will notice that all of the previous components are in the geronimo.server domain. In fact, all deployed application components will be in this domain. Table 7-3 describes all the JSR-77 domains used in object names in Geronimo.

Table 7-3: Geronimo’s JSR-77 Domains Open table as spreadsheet
Geronimo’s JSR-77 Domain Name | Description
geronimo.boot | Component used during kernel boot.
geronimo.config | Currently running or recently failed configurations in the server.
geronimo.remoting | Server for JAAS remote login.
geronimo.security | Component representing the keystore, and perhaps other security components in the future.
geronimo.server | The application components that have been deployed. This domain is where you will find most of the interesting components.
geronimo and openejb | OpenEJB system components.

You should now have a workable understanding of how components in a server are given JSR-77 names. In the upcoming debug console troubleshooting example, you can put this knowledge to good use.

Understanding JSR-77 object naming conventions is very important to system administrators. In addition to their use in the debug console, you can also reference Geronimo managed objects in deployment plans using the JSR-77 naming conventions.

JSR-77 Manageable States

As mentioned, every JSR-77 manageable object is an instance of a J2EEManagedObject. A J2EEManagedObject has a mandatory Boolean attribute called stateManageable. If this attribute is valued true, it indicates that the container is managing the lifecycle of the component. This is always the case with deployable application modules in Geronimo.

A JSR-77 stateManageable component can have its state queried by a JSR-77 client application. It is also possible to find out how long a component has been running, or start and stop the component using the exposed operations.

A JSR-77 stateManageable component can be in any one of the following states:

  • Starting

  • Running

  • Stopping

  • Stopped

  • Failed

These are the states that every deployable Geronimo application component may be in. The possible state transitions are shown in Figure 7-5.

Image from book
Figure 7-5: State transitions and JSR-77 manageable states

As a JSR-77 client application, the debug console can show you the JSR-77 state of managed components. This information is invaluable in many troubleshooting scenarios.

It is time to get some hands-on working time with the debug console tool.


Installing the Debug Console

Releases of Geronimo prior to 1.1 included the debug console as part of the downloadable binary distribution. Geronimo release 1.1, however, does not include the application.

Instead, you can obtain the debug console by installing it as a plug-in. The debug console plug-in is downloadable from this book’s companion Web site (www.wrox.com/...) as a ZIP file.

To install the downloaded geronimo-debug-console.zip plug-in, you can use the following deployer command:

deploy install-plugin geronimo-debug-console.zip


Starting the Debug Console

After installing the plug-in, ensure that the module has started (from either the deployer or the Web console). If it has not been started, you can start the debug console from the command line by starting the geronimo/debugconsole/1.1/car module, or use the Web console. From the command line, in the bin directory, you can enter the following:

deploy –user system –password manager start geronimo/debugconsole/1.1/car

From the Web console, click on the Web App WARs link under the Applications heading, and then click the start link next to the geronimo/debugconsole/1.1/car configuration. Figure 7-6 shows the debug console configuration started in the Geronimo Web console.

Image from book
Figure 7-6: Debug console configuration started in Geronimo console

You can also stop the debug console, if you need to, through the Geronimo Web console.

Starting the jconsole JMX Console

jconsole is the GUI-based JMX console tool that is included with JDK 1.5 and beyond. jconsole provides you with visibility into the exposed MBeans in a system. It can connect to a local JVM or to a remote JVM over a network.

If you are running JDK 1.5 and want to monitor Geronimo and troubleshoot with jconsole, you need to do the following:

  1. Configure Geronimo JVM to accept remote management.

  2. Start Geronimo.

  3. Start jconsole.

  4. Connect jconsole to the running instance of Geronimo.

Each of these steps is detailed in the following subsections.

Configuring Geronimo JVM to Accept Remote Management

This is actually performed at the JVM level. A property, com.sun.management.jmxremote, must be defined. This is best done by modifying the bin/setjavaenv.bat script file (or equivalent bin/setjavaenv.sh for Linux/*nix). This script is executed before Geronimo is started.

If you set a GERONIMO_OPTS environment variable in this file, the value of this variable will be used as JVM arguments to the JVM that Geronimo runs in.

In this case, add the lines highlighted in the following listing to your copy of bin/setjavaenv.bat. Of course, you should make this modification only after you have shut down the Geronimo server (if it is already running).

...
@REM Begin all @REM lines with '@' in case GERONIMO_BATCH_ECHO is 'on'
@if "%GERONIMO_BATCH_ECHO%" == "on"  echo on
@if not "%GERONIMO_BATCH_ECHO%" == "on"  echo off

set GERONIMO_OPTS=-Dcom.sun.management.jmxremote

@REM check that either JAVA_HOME or JRE_HOME is set.
set jdkOrJreHomeSet=0
...

Start Geronimo

Run the startup.bat (or startup.sh) script located in the bin directory to start the Geronimo server.

Start jconsole

You should first ensure that you have the bin directory of your JDK 1.5 in your PATH environment variable. Starting jconsole is then as simple as typing the following command:

jconsole

If you want to attach jconsole to a specific instance of Geronimo running on the same host, you must first find the instance’s process ID. Use the Task Manager on Win32 or the ps command in Linux/*nix.

Then, the command is:

jconsole  <process id of Geronimo>

Connect Geronimo to jconsole

If you have specified the process ID when you start jconsole, it will be connected to the Geronimo instance upon startup. Otherwise, jconsole will detect any available local running and exposed JVM instance. You see a selection screen similar to Figure 7-7.

Image from book
Figure 7-7: jconsole local running JVM section dialog

If you are using Win32, you must be using NTFS for your file system to see this list.

Select the instance and click Connect.

If you need to connect to a remote instance running on another machine, use the Remote tab of the dialog and provide the remote host/IP and port used.

Once you have connected successfully, you should see the first screen of monitored statistics on the Geronimo JVM, as shown in Figure 7-8.

Image from book
Figure 7-8: A successful connection to the Geronimo JVM

Accessing the Debug Console

Once it is started, you can access the debug console using a browser via the following URL:

http://localhost:8080/debug-tool/

Figure 7-9 shows the initial display of the debug console.

Image from book
Figure 7-9: Initial display of the debug console

One thing that you will notice immediately in Figure 7-9 is the raw appearance of the display. Unlike the Web console, which is designed for frequent user and administrator use, the debug console is really designed only for developers and expert administrators. Because of this heritage, the debug console is not dressed up with GUI elements.

Looking through the initial page, you should recognize some Geronimo JSR-77 domain names, and also some links that look like JSR-77 object names.

In Figure 7-9 , the objects in the geronimo.config and geronimo.boot domain are not standard J2EE typed objects. They are specific to Geronimo. As such, they do not need the j2eeType key or any mandatory parent j2eeType keys. But if you scroll down and take a look at the objects under the geronimo.server domain, you will see all the j2eeType components there.

Filtering the Components That Are Displayed

There is a Filter Output button at the top. This area lets you specify a filter to select the MBeans that are displayed. The general syntax of this filter is:

<domain name>:<key value to match>

An asterisk (*) can be used to denote wildcard match. Initially, the filter is *:*, which will match all the available MBeans across all available domains. In the case in Figure 7-9, there are a total of 179 MBeans managed by the kernel.

If you want to see all the MBeans from deployed application components, for example, you may enter the following:

geronimo.server:*

This will show all the components in the geronimo.server domain - which according to Table 7-3 is the domain where deployed application components live.

Figure 7-10 shows the result of this filtering.

Image from book
Figure 7-10: Querying for deployed application components by using a domain filter

In Figure 7-10, you have used the filter on geronimo.server domain to query the debug console for all deployed application components.

Note in Figure 7-10, the very first object is a StatelessSessionBean (j2eeType) with name ejb/mgmt/MEJB. This is the very MEJB component that the debug console is using to query for MBean information! If you look through the other objects in this domain, you will find components in every deployed application. All of these objects have JSR-77 object names. You can confirm this against Table 7-2. Now you can see how an understanding of JSR-77 object name helps in the use of the debug console.

Note that the current JSR-77 managed state is shown beside each and every component inside the square bracket [...]. This state information is used frequently in troubleshooting when a module may have stopped or failed silently. The Web console can also be used to display some of these states, but it may not be as reliable and often does not display all the possible state variations

If you are using jconsole, just click on the MBeans tab, then select geronimo in the displayed tree. Select the geronimo.geronimo subtree. Figure 7-11 shows the components exposed via jconsole.

Image from book
Figure 7-11: jconsole display of Geronimo MBeans


Troubleshooting a Deployment - An Example

Not every one of your deployments will be successful. It is important for an administrator to know what to do when a deployment does not work. This example walks you through the steps in troubleshooting what went wrong when a module does not deploy.

To try out the example, look for the source code download at the book’s companion Web site. Look under the debugconsole directory, where you will find two elements:

  1. A deployable EAR called progeron.ear

  2. A deployment plan called deploy.xml

Now, deploy this application using either the command line or the Web console. Using the Web console, select the Deploy New link beneath the Applications heading. Enter the progeron.ear as Archive and the deploy.xml as plan.

Click on the Install button. You should get a blank page because of deployment problem. The deployment has obviously failed. You need more information to troubleshoot this deployment.

Checking Console Output

The first place to check when the Web console gives you a blank page is the operating system console window where Geronimo has started. In this case, there is a Java exception trace displayed in the console. A portion of this trace is shown here:

Deployer operation failed: org.apache.xmlbeans.XmlException: Invalid deployment
descriptor: [error: cvc-complex-type.2.4a: Expected elements 'module@http://gero
nimo.apache.org/xml/ns/j2ee/application-1.1 ext-module@http://geronimo.apache.or
g/xml/ns/j2ee/application-1.1 security@http://geronimo.apache.org/xml/ns/securit
y-1.1 gbean@http://geronimo.apache.org/xml/ns/deployment-1.
id@http://geronimo.apache.org/xml/ns/j2ee/application-1.
Descriptor: <xml-fragment xmlns:dep="http://geronimo.apache.org/xml/ns/deploymen
t-1.1" xmlns:app="http://geronimo.apache.org/xml/ns/j2ee/application-1.1">
  <dep:environment>
    <dep:moduleId>
      <dep:groupId>wrox</dep:groupId>
      <dep:artifactId>progeron</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
  </dep:environment>
  <app:notvalid/>
  <app:module>
    <app:ejb>progeron-ejbs.jar</app:ejb>
    <openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1">
      <enterprise-beans>
        <session>
          <ejb-name>AuthorEJB</ejb-name>
          <jndi-name>ejb/AuthorEJB</jndi-name>
        </session>
      </enterprise-beans>
    </openejb-jar>
  </app:module>
  <app:module>
    <app:web>progeron.war</app:web>
    <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.1"></web
-app>
  </app:module>
</xml-fragment>
org.apache.geronimo.common.DeploymentException: org.apache.xmlbeans.XmlException
: Invalid deployment descriptor: [error: cvc-complex-type.2.4a: Expected element
s 'module@http://geronimo.apache.org/xml/ns/j2ee/application-1.1 ext-module@http
...
        at org.apache.geronimo.schema.SchemaConversionUtils.validateDD(SchemaCon
versionUtils.java:605)
        at org.apache.geronimo.schema.SchemaConversionUtils.fixGeronimoSchema(Sc
hemaConversionUtils.java:370)
        at org.apache.geronimo.j2ee.deployment.EARConfigBuilder.getEarPlan(EARCo
nfigBuilder.java:327)
        ... 21 more

In most cases (such as this one), the console trace output will put you on the right track to narrow down the problem. The boldfaced part of the preceding trace output says that there is a schema validation problem. Specifically, the schema is invalid because of an unexpected element called notvalid.

If the information on the console has scrolled away, or if you are running Geronimo as a service on the system, you may not be able to get this useful trace diagnostic. In this case, you must turn to the log for this information.

Examining the Geronimo Log File

All of the exceptions displayed on the command console are also captured in the Geronimo log file. You can find the log in the var/log directory, called geronimo.log. You can examine the log using a plain-old text editor. You will find the same exception information, shown in the following listing.

05:43:02,296 DEBUG [Deployer] Deployment failed: plan=C:\gerbuild\geronimo-
1.1\var\temp\deploy.xml, module=C:\gerbuild\geronimo-1.1\var\temp\progeron.ear
org.apache.geronimo.common.DeploymentException: org.apache.xmlbeans.XmlException:
Invalid deployment descriptor: [error: cvc-complex-type.2.4a: Expected elements
'module@http://geronimo.apache.org/xml/ns/j2ee/application-1.1 ext-
module@http://geronimo.apache.org/xml/ns/j2ee/application-1.1
security@http://geronimo.apache.org/xml/ns/security-1.1
gbean@http://geronimo.apache.org/xml/ns/deployment-1.1' instead of
'notvalid@http://geronimo.apache.org/xml/ns/j2ee/application-1.1' here]
Descriptor: <xml-fragment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-
1.1" xmlns:app="http://geronimo.apache.org/xml/ns/j2ee/application-1.1">
  <dep:environment>
    <dep:moduleId>
      <dep:groupId>wrox</dep:groupId>
      <dep:artifactId>progeron</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
  </dep:environment>
  <app:notvalid/>
  <app:module>
    <app:ejb>progeron-ejbs.jar</app:ejb>
    <openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1">
      <enterprise-beans>
        <session>
          <ejb-name>AuthorEJB</ejb-name>
          <jndi-name>ejb/AuthorEJB</jndi-name>
        </session>
      </enterprise-beans>
    </openejb-jar>
  </app:module>
  <app:module>
    <app:web>progeron.war</app:web>
    <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.1"></web-
app>
  </app:module>
</xml-fragment>
     at
org.apache.geronimo.j2ee.deployment.EARConfigBuilder.getEarPlan(EARConfigBuilder.ja
va:345)
     at
org.apache.geronimo.j2ee.deployment.EARConfigBuilder.getDeploymentPlan(EARConfigBui
lder.java:263)
     at
org.apache.geronimo.j2ee.deployment.EARConfigBuilder$$FastClassByCGLIB$$38e56ec6.in
voke(<generated>)
     at net.sf.cglib.reflect.FastMethod.invoke(FastMethod.java:53)
     at
org.apache.geronimo.gbean.runtime.FastMethodInvoker.invoke(FastMethodInvoker.java:3
8)
     at
org.apache.geronimo.gbean.runtime.GBeanOperation.invoke(GBeanOperation.java:122)
     at
org.apache.geronimo.gbean.runtime.GBeanInstance.invoke(GBeanInstance.java:817)
     at org.apache.geronimo.gbean.runtime.RawInvoker.invoke(RawInvoker.java:57)
     at
org.apache.geronimo.kernel.basic.RawOperationInvoker.invoke(RawOperationInvoker.jav
a:35)
     at
org.apache.geronimo.kernel.basic.ProxyMethodInterceptor.intercept(ProxyMethodInterc
eptor.java:96)
     at
org.apache.geronimo.deployment.ConfigurationBuilder$$EnhancerByCGLIB$$42a16177.getD
eploymentPlan(<generated>)
     at org.apache.geronimo.deployment.Deployer.deploy(Deployer.java:232)
     at org.apache.geronimo.deployment.Deployer.deploy(Deployer.java:124)
     at
org.apache.geronimo.deployment.Deployer$$FastClassByCGLIB$$734a235d.invoke(<generat
ed>)
     at net.sf.cglib.reflect.FastMethod.invoke(FastMethod.java:53)
     at
org.apache.geronimo.gbean.runtime.FastMethodInvoker.invoke(FastMethodInvoker.java:3
8)
     at
org.apache.geronimo.gbean.runtime.GBeanOperation.invoke(GBeanOperation.java:122)
     at
org.apache.geronimo.gbean.runtime.GBeanInstance.invoke(GBeanInstance.java:852)
     at org.apache.geronimo.kernel.basic.BasicKernel.invoke(BasicKernel.java:239)
     at
org.apache.geronimo.deployment.plugin.local.AbstractDeployCommand.doDeploy(Abstract
DeployCommand.java:106)
     at
org.apache.geronimo.deployment.plugin.local.DistributeCommand.run(DistributeCommand
.java:60)
     at java.lang.Thread.run(Thread.java:595)
Caused by: org.apache.xmlbeans.XmlException: Invalid deployment descriptor: [error:
cvc-complex-type.2.4a: Expected elements
'module@http://geronimo.apache.org/xml/ns/j2ee/application-1.1 ext-
module@http://geronimo.apache.org/xml/ns/j2ee/application-1.1
security@http://geronimo.apache.org/xml/ns/security-1.1
gbean@http://geronimo.apache.org/xml/ns/deployment-1.1' instead of
'notvalid@http://geronimo.apache.org/xml/ns/j2ee/application-1.1' here]
Descriptor: <xml-fragment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-
1.1" xmlns:app="http://geronimo.apache.org/xml/ns/j2ee/application-1.1">
  <dep:environment>
    <dep:moduleId>
      <dep:groupId>wrox</dep:groupId>
      <dep:artifactId>progeron</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
  </dep:environment>
  <app:notvalid/>
  <app:module>
    <app:ejb>progeron-ejbs.jar</app:ejb>
    <openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1">
      <enterprise-beans>
        <session>
          <ejb-name>AuthorEJB</ejb-name>
          <jndi-name>ejb/AuthorEJB</jndi-name>
        </session>
      </enterprise-beans>
    </openejb-jar>
  </app:module>
  <app:module>
    <app:web>progeron.war</app:web>
    <web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.1">
</web-app>
  </app:module>
</xml-fragment>
     at
org.apache.geronimo.schema.SchemaConversionUtils.validateDD(SchemaConversionUtils.j
ava:605)
     at
org.apache.geronimo.schema.SchemaConversionUtils.fixGeronimoSchema(SchemaConversion
Utils.java:370)
     at
org.apache.geronimo.j2ee.deployment.EARConfigBuilder.getEarPlan(EARConfigBuilder.ja
va:327)
     ... 21 more

Other than using your favorite text editor, you can also use the log viewer in the Web console. Check under Server logs link under the Server heading. One benefit of using the Web console is that it allows you to search through the log, which can be advantageous when the log is very large.

Correcting the Deployment Plan

Both the console output and the log point to a bad element called <notvalid> in the deployment plan. If you examine the deployment plan, you will find this offending element, shown in the following listing.

<?xml version="1.0" encoding="UTF-8"?>
<application
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1">
      <environment>
      <moduleId>
        <groupId>wrox</groupId>
         <artifactId>progeron</artifactId>
         <version>1.0</version>
         <type>car</type>
       </moduleId>
       </environment>

<notvalid/>

<module>
        <ejb>progeron-ejbs.jar</ejb>
        <openejb-jar
            xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1"
            >
            <enterprise-beans>
                <session>
                    <ejb-name>AuthorEJB</ejb-name>
                    <jndi-name>ejb/AuthorEJB</jndi-name>
                </session>
            </enterprise-beans>
        </openejb-jar>
    </module>...

Correct the deployment plan by removing the <notvalid/> element. Try deploying the EAR file with the plan again.

You can use the deployer or the Web console to deploy progeron.ear with the updated deploy.xml.

This time, the deployment should be successful.

Querying Components from a Deployed Application on the Debug Console

Point your browser to the debug console. In the Filter Output text box of the debug console, enter the following JSR-77 name pattern:

*:J2EEApplication=progeron

This tells the debug console (and actually the JSR-77 MEJB) that you want all the objects in the J2EEApplciation called progeron, across any domain. This query selects all the deployed objects in the progeron application. Figure 7-12 shows the resulting set of managed objects.

Image from book
Figure 7-12: Debug console query results for objects in the progeron application

In Figure 7-12, you can see the AuthorEJB stateless session bean as well as the Show authors servlet component. The JSR-77 object name describes each object precisely.

If you are using jconsole, select the geronimo.geronimo.AuthorEJB node, and also the geronimo.geronimo.ShowAuthors node to view the component details. Figure 7-13 shows these application objects in jconsole.

Image from book
Figure 7-13: Objects in the progeron application in jconsole

Viewing the Attributes of a Geronimo Managed Object

Every JSR-77 name listed in the debug console is a hyperlink. If you click on any of the object links, the debug console will access the MBean and display the value of all the attributes on the MBean. It will be shown on the right-hand side of the debug console browser. You may have to scroll horizontally to see the list of MBean attributes. For example, if you click on the AuthorEJB stateless session bean, you will see all its properties (see Figure 7-14).

Image from book
Figure 7-14: Debug console displaying the MBean attributes for the AuthorEJB session bean

You can see from Figure 7-14 that quite a bit of information concerning the deployed components is available via the MBean attributes. Many of the attributes (such as defaultPrincipal, ejbName, jndiNames, localJndiNames, and runAsSubject) are configurable in the application deployment plan. The ability to see the actual run-time value of these attributes will help you to troubleshoot problems - especially in the cases where the value set in the deployment plan may be incorrect.

To familiarize yourself with the attributes that are available for different components, click on other managed components, and notice the available attributes and their assigned value. You may want to refer to the component’s deployment plan to see how the attributes are set during deployment

If you are using jconsole, the AuthorEJB appears as a separate component at the top of the geronimo.geronimo subtree displayed by the MBeans tab. Figure 7-15 shows the jconsole display of the properties of the AuthorEJB session bean.

Image from book
Figure 7-15: jconsole displaying details for the AuthorEJB session bean


Summary

The Geronimo debug console, while not a fancy GUI tool, is a hardcore administrator’s tool that will display information on all the objects managed by the Geronimo kernel.

Since the objects expose their properties via JMX, JDK 1.5’s GUI JMX console called jconsole can also be used to display managed object information.

The Geronimo kernel manages components called GBeans. Every GBean can be externally manageable if the designer of the GBean exposes Java Management Extension (JMX) attributes or operations.

JMX specifies how Java-based software components, servers, or devices can be managed by network-management applications. The JMX model has three levels: Instrumentation, Agent, and Distributed Services.

At the JMX instrumentation level, MBeans are created. An MBean provides a management interface for a software component, service, or device. MBeans are created without concern for the Agent level. At the Agent level, an MBean server aggregates MBeans and interfaces them to external network-management application or applications at the Distributed Services level.

JSR-77 is a J2EE management specification that uses JMX to specify how J2EE servers and software components can be made manageable. Specifically, JSR-77 enables compatible clients (management applications) to be created and used on any compatible server. JSR-77 clients obtain MBean information on managed component via a Management EJB (MEJB).

The Geronimo debug console is a Web application running in Geronimo that is actually a JSR-77 client. It queries the MEJB, implemented by Geronimo, for Geronimo component information.

JSR-77 specifies a standard J2EE object naming convention that reveals the hierarchical relationship between J2EE components. This convention is used to query for objects using the debug console.

Troubleshooting deployment using the debug console boils down to querying the console using the JSR-77 name pattern to locate a managed object and then viewing the state and/or attributes of the component’s JMX MBean. You have walked through a typical deployment troubleshooting scenario in this chapter.

Moving from a low-level, hardcore tool to a high-level, do-all utility, Chapter 8 looks at the capabilities of the Geronimo Web console.


Chapter 8: Geronimo Web Console

Overview

The Geronimo Web console is easily the single most frequently used tool on Geronimo. It aims to be a one-stop shop for all your Geronimo administration, configuration, and management needs.

The Web console provides a friendly user interface for frequently performed administration, configuration, and management tasks. For some daily administration tasks, the Web console can eliminate the need to use tedious command-line tools.

This chapter introduces the Web console, reveals that it is just another Geronimo-hosted application, and then walks you through all the features supported by the Web console.

You can use the Web console to:

  • Perform server administration tasks

  • Configure and manage system services and resources

  • Deploy and manage applications

  • Install or create plug-ins

  • Set up container-managed security

  • Manage and configure a system database

In this chapter, each of these functional areas is explored. You will visit many of the user-interface screens in the Web console and get an overview understanding of the purpose for every functional area of the Web console. The tasks that are performable through the Web console will be explained, and references will be drawn to other chapters in this book for a more detailed exploration.

To add even more value to your journey through the Web console, the exploration will be paralleled with an explanation of how to perform some of the Web console tasks using the command-line alternatives (if available). This will fortify your understanding of the relationship between the command-line tools and the Web console. It can also serve as a handy reference for the rainy days when the Web console cannot be accessed.

By the end of the chapter, you will be fluent in the usage of the Web console. You will be able to use the console for many of your daily administrative and configuration tasks.


Using the Web Console

Before delving into the specifics of how to work with the Web console, it is important to understand the basic setup of what you will be seeing, as well as how to actually access this important tool.

Web Console Architecture

The Web console is implemented as a set of portlets. Portlets are mini-applications that interact with the user as a rectangular area within a displayed Web page. The portlets in the Geronimo console are created using Apache Pluto. Geronimo has the Pluto libraries in its repository, allowing developers to use the portlet technology in any applications deployed to Geronimo. The programming API and object model for portlet programming is the subject matter of JSR-168 (see www.jcp.org/en/jsr/detail?id=168 for more information).

The Web console itself is a Web application running on Geronimo. In fact, if you examine the startup message of the Geronimo server, you should see the Web console application loading in messages similar to the following:

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

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

In the top-right corner of each portlet window, there is usually a help and view links. Clicking on the help link provides a page of help information. You will find some very useful information in these help pages. Many common questions and usage patterns for each portlet are fully documented in the help pages. If you click the view link, it will take you right back to the functional page of the portlet itself.

Logging on to the Web Console

You can access the Geronimo Web console at the following URL:

http://localhost:8080/console/

You will need to log in before using the console. The default user=system, password=manager will work for console login. Figure 8-1 shows the Geronimo Web console login page.

Image from book
Figure 8-1: Logging on to the Geronimo Web console

The menus are on the left-hand side. You can add additional users who are allowed to access the console.

Adding More Console Users

If you need to add users, they may be added to the default console security realm by selecting the Security→Console Realm menu.

For our purposes, a security realm can be thought of as a database containing user, group, and password information. Chapter 15 explores in more details of exactly what a security realm is.

By default, the console realm uses the server-wide default geronimo-properties security realm.

Editing Properties Files

This realm makes use of two property files in the var/security directory, namely the following files:

  • groups.properties - Specifies the groups and the users in them

  • users.properties - Specifies the users and passwords

Let’s add a user called bruce with the password test. First, add the user bruce to the admin group. The admin group is the group that includes the Web console users. This can be done by adding the user bruce to the groups.properties file, shown in bold in the following listing:

admin=system,bruce

Next, add a line with the user bruce and the password test in the users.properties file. This addition is shown in the following listing:

system=manager
bruce=test

That’s it. Now, start the Geronimo server and try logging in with the new user. Now you can use either system/manager or bruce/test for accessing the Geronimo Web console.

Adding a New User through Web Console

To add the same user via the Web console, follow these steps:

  1. Select Security→Console Realm menu.

  2. Click on the Create New User link in the Console Realm users portlet.

  3. Add the new user bruce with password test.

  4. Click on the admin group link in the Console Realm Groups portlet.

  5. Add the bruce user to the group by clicking the Add button, then the Update button.

This series of action performs exactly the same task as editing the properties files. If you check the users.properties and groups.properties file, you can verify the change.


Navigating the Server’s Functional Menus

This section explores the menu options listed in the main category of the server on the Web console GUI.

Obtaining System Information on the Geronimo Server

You can select Server→Information to display system information such as kernel uptime and JVM memory usage. This information is updated in real time as it changes in a graph. This Server Memory Usage portlet uses Ajax (Asynchronus Javascript And XML) technology to perform periodic live updates. Figure 8-2 shows a typical display of system information. Note that not all versions of JDK supports this real-time update, and you may not see a live update display.

Image from book
Figure 8-2: Real-time system information display

Viewing Java Virtual Machine Properties

If you click the Server→JVM link, you will see the value to many of the Java system properties for this JVM. This can be quite useful when you are troubleshooting and wondering what the value of a particular system property may be set to.

Viewing and Searching Log Files

You can use the Web console to view and search through log files. Server components within Geronimo logs regularly refer to these files. If you click the Server→Server Logs link, you will see three log-related portlets:

  • Log Manager - For configuring the server settings related to logging on the server

  • Server Log Viewer - For viewing the general Geronimo server log

  • Derby Log Viewer - For viewing the logs from the embedded Derby system database

  • Web Access Log Viewer - For viewing the access log for Tomcat or Jetty, depending on the Geronimo distribution that you are using

Figure 8-3 shows the page of log viewer portlets.

Image from book
Figure 8-3: Viewing and searching logs with Geronimo Web console

In Figure 8-3, the Log Manager portlet modifies a Log4J configuration file according to your settings. This configuration file is used by the server’s logging code. You can control the attributes shown in Table 8-1.

Table 8-1: Log Manager Attributes Open table as spreadsheet
Attribute | Description
Config File | The configuration file used by the server. By default, this is var/log/server-log4j.properties. There should be little need to change this.
Refresh Period | Time in seconds between checks made by the server to the configuration file. This is the maximum time that you may have to wait before your setting changes take effect. The default is 60 seconds.
Log Level | The logging level. The different levels control both the volume of logging information and the type of information logged. The possible values are DEBUG, INFO, WARN, ERROR, FATAL, and TRACE. There are also the values of ALL to print all logs (highly verbose) and OFF to disable logging.

With the Server Log Viewer portlet, you can search through the entire log (often thousands of lines long) filtering through specific log level, looking for entries containing text that you specify. You can limit the number of lines returned in the result, as well as the range of lines that the viewer will search through.

The Derby Log Viewer portlet shows lines from the system database log file and allows you to filter by line number range and specific matching text.

The Access Log Viewer portlet allows you to search through either the Tomcat or the Jetty access logs (depending on the distribution you are using), capturing the access statistics. You can filter the access entries by date range, by the remote address, authenticated username, the HTTP request method, or the actual request URI.

Shutting Down the Server

Selecting Server→Shutdown will show a Server Manager portlet with one single Shutdown button. Clicking this button will shut down the server gracefully. This shutdown is equivalent to pressing Ctrl+C at the system console that is running Geronimo, or running the shutdown batch file in the bin directory.

Figure 8-4 shows the Server Shutdown portlet with the single button.

Image from book
Figure 8-4: The Server Manager portlet for system shutdown

Configuring Web Server Connectors

Selecting Server→Web Server takes you to the Web Server Manager portlet. In this portlet you can:

  • Enable or disable the Web server statistics display

  • Configure and control connectors for Tomcat or Jetty

Figure 8-5 shows the Web Server Manager portlet and network connector configuration portlets.

Image from book
Figure 8-5: Configuration of Web server connectors with Web console

You can start the Web server’s collection of statistics by clicking the Enable link in the Web Server Manager portlet. Figure 8-6 shows the statistics that are collected and displayed by this portlet.

Image from book
Figure 8-6: The statistics shown by the Web Server Manager portlet

Table 8-2 describes the different types of Web server connectors that you can add to either Jetty or Tomcat.

Table 8-2: Web Server Connectors Open table as spreadsheet
Connector type | Description
HTTP | Handles regular non-secure HTTP protocol.
HTTPS | Handles SSL-based secured HTTP connections.
AJP | Connector for AJP protocol - typically used to connect between the server engine and a front-end Web server (such as the Apache Web server).

Multiple connectors, listening to different ports, may be configured at the same time with the same Jetty or Tomcat engine. Each connector handles connections using a different communication protocol. Multiple instances of the same connector, listening to different TCP port, may also be configured. Figure 8-7 shows some configuration possibilities.

Image from book
Figure 8-7: Web Server Network connectors configuration possibilities

In Figure 8-7, the Jetty or Tomcat engine is configured with two HTTP connectors. Users can access the Geronimo-managed applications via HTTP port 8080 or port 8085. A secure connection is available via an HTTPS connector, on port 8443. There is also an AJP connector (on port 8019) that talks to an external Web server - allowing access of the Geronimo-managed application through the Web server.

Note that if you have conflict in these ports when the server is started, it may not be possible to alter their values in the Web console. In this case, you must shut down the server and edit the var/config/config.xml file to resolve the conflict and change their values.

Configuring and Controlling the ActiveMQ JMS Server

If you click on Server→JMS Server, the portlets here enable you to start/stop, configure, or add both the ActiveMQ message broker (JMS server) instances, as well as ActiveMQ network connectors to the various transports.

ActiveMQ supports a large variety of transport protocols. Each transport protocol that you configure will enable ActiveMQ clients to connect into the server using that protocol.

By default, Geronimo starts one instance of the ActiveMQ message broker as the J2EE container’s JMS server. This instance is named ActiveMQ.

Chapter 16 has more detailed information on working with the ActiveMQ message broker, and configuration of connectors.

Figure 8-8 shows the JMS server configuration portlets on the Web console.

Image from book
Figure 8-8: Configuring ActiveMQ message broker and connectors with Geronimo Web console

In Figure 8-8, a single instance of the ActiveMQ message broker is running inside Geronimo. This is the default configuration.

In Figure 8-8, two network connectors have been configured. They are vm and tcp connectors, respectively. The vm connector uses fast intra–Java VM communications to speed up connections between Geronimo components and the hosted ActiveMQ message broker, while the tcp connector listen to port 61616 for incoming clients over the TCP/IP network.

Monitoring Thread Pools

Concurrent requests are processed in separate threads to improve system throughput in the Geronimo servers. There are several different pools of threads that are managed by Geronimo.

If you select the Server→Thread Pools menu option, this will display the Thread Pool Configuration portlet. In Geronimo 1.1, this portlet is still a work in progress, and displays the usage of threads in only two of the available pools.

Figure 8-9 shows the Thread Pool Configuration portlet.

Image from book
Figure 8-9: Thread Pool Configuration portlet and available thread pools

In Figure 8-9, the ConnectorThreadPool and DefaultThreadPool are available for monitoring. If you click the corresponding monitor link, the associated thread usage statistics will be displayed.

Exposing Geronimo Applications via a Web Server

The Server→Apache HTTP menu enables you to expose Web applications hosted on Geronimo through an Apache Web server front-end using mod_jk (using the AJP protocol). This menu starts the Apache mod_jk Configuration portlet.

Look back at Figure 8-6 to see a Web Server connected to Geronimo via the AJP connector. The mod_jk module in Apache handles the requests forwarding to the Geronimo server. You must configure this module to point it to the AJP connector listening in Geronimo. This is done through a worker.properties file, plus modification to the httpd.conf file of the Apache server.

This Apache mod_jk Configuration portlet can provide customized instructions for configuration. On some Linux systems, it can even perform editing of the required configuration files for you. Before you start, you must make sure that the application that you want to expose through Apache is already installed and running.

The instructions provide by this portlet are very detailed and are straightforward to follow.

Figure 8-10 shows the Apache mod_jk Configuration portlet’s configuration screen.

Image from book
Figure 8-10: Use the Apache mod_jk Configuration Portlet to expose the application

In Figure 8-10, the portlet’s Web Application Selection screen is shown. Here, you can select the running Web application that you want exposed through the Apache Web Server. In addition, you can also choose to enable Apache to serve static content from the application.

Note that Geronimo, in both the Tomcat and Jetty distribution, already has the ability to act as a standalone Web server. Configuration of a front-end Apache server is necessary typically for high-volume deployment scenarios.


Navigating the Services Functional Menus

This section explores the menu options listed in the main category of the Services on the Web console GUI.

Installing Artifacts into the Geronimo Repository

The Geronimo repository is where the server stores and keeps track of the binary executables. It is also the place where Geronimo configurations are stored. For example, you will find the binary JAR files for both Tomcat and OpenEJB in the repository.

Any <dependency> element that you see in a system deployment plan may be referring to some files (called artifacts) in the repository.

The repository, as explained in Chapter 5 stores the binaries and configurations under the repository directory. Every artifact is stored under a directory that match its coordinate. The coordinate consists of (organization/group, artifact id, version, type). This coordinate system is also used for storing configuration of deployed modules - matching the deployed module’s module ID.

All of the binaries stored in the repository are in JAR format but may be named WAR, EAR, RAR, JAR- depending on the type of archive. The general directory hierarchy of the repository is shown in Figure 8-11.

Image from book
Figure 8-11: Directory hierarchy of the Geronimo repository

In Figure 8-11, note that you can readily identify the organization/group that owns the artifacts by the top-level directory name (sometimes multiple top-level directories). For example, the ActiveMQ binaries are located under the activemq directory in the repository.

The level below the organization is the artifact ID level. In the case of activemq in Figure 8-11, there are three artifacts: activemq-core, activmq-gbean-g1_1, and activemq-gbean-management-g1_1.

Underneath the artifact ID directory level is the version level. In Figure 8-11, the 3.2.4 directory underneath the activemq\activmq-core directory is the version directory.

Finally, you will find the stored JAR file underneath the version directory. In the case of Figure 8-11, the actual artifact is stored as activemq-core-3.2.4.jar.

In the Web console, if you select Services→Common Libraries, you will see the repository viewer portlet. Figure 8-12 shows the Repository Viewer portlet.

Image from book
Figure 8-12: The Repository Viewer and Installation portlet

Using the Repository Viewer portlet, not only can you see all the individual artifacts that are stored in the repository (including the complete path to the artifact, reflecting its associated coordinate), but you can also add additional artifacts to the repository. Typically, you will only add artifacts to the repository if you need to install code that is integrated as part of the system common library. For example, you may want to add a JDBC driver to an RDMBS that is accessible by all applications running on your Geronimo server.

To install a new artifact, just click the Browse button, then browse to the artifact stored on your disk, then supply its coordinate information (group, artifact ID, version, type), and then click the Install button.

Once an artifact is installed into the repository, any deployed application can refer to it via a <dependency> element that specifies its coordinate. For example, if you deployed a library called tools-3.2.jar with coordinates (wrox, tools, 3.2, jar), it can be referenced as wrox/tools/3.2/jar in a <dependency> element.

Installing Database Pools

J2EE applications deployed in Geronimo may access any RDBMS via JDBC. JDBC operations require a driver specific to the RDBMS that you are connecting to. Geronimo can manage and pool JDBC connections for efficient access to the RDBMS. Internally, Geronimo uses TranQL to provide database connection pooling.

The Database Pools portlet can help you create a Geronimo-managed database pool. Database pools managed by Geronimo can be accessible systemwide or be specific to an application. Only systemwide pools can be edited using the portlet. You can access the database pool configuration portlet by selecting Services→Database Pools. Figure 8-13 shows the Database Pools configuration portlet.

Image from book
Figure 8-13: The Database Pools configuration portlet

In Figure 8-13, the portlet shows one single systemwide accessible SystemDatabasource pool. You can click the edit link to see or change the configuration parameters of the pool. You can also click the usage link to see how to configure your deployment plans, within a Geronimo-hosted application, to use this database pool.

Using the Geronimo Database Pool Wizard, you can create a new datasource for use systemwide. The wizard will guide you step by step through the process. The binary of the JDBC driver must either be installed previously to the repository (perhaps using the Repository Viewer portlet) or downloaded by Geronimo during the process. The Geronimo console supports automated downloading and installation of a small set of well-known drivers. This set of drivers may change in the future and currently includes drivers downloads for MySQL, PostgreSQL, HSQLDB, Sybase, and so on.

If you are migrating from another server, the Database Pools configuration portlet also allows you to import a database pools configuration directly from the following:

  • JBoss 4

  • BEA Weblogic 8.1

A step-by-step wizard will guide you through the configuration import process.

Creating JMS Resource Groups

JMS resource groups are grouping of message destinations with its associated connection factory. Message destinations are message queues or topics that JMS applications can send messages to or receive messages from. You can set up new JMS resource groups using the Web console.

Select Services→JMS to access the JMS Resources portlet, as shown in Figure 8-14.

Image from book
Figure 8-14: Creating JMS resource groups

JMS connection factories are like JDBC drivers; they are JCA connectors. Think of them as binary code that represents drivers to different servers, a message broker in the former case and an RDBMS in the latter case. With Geronimo, a JMS connection factory manages a pool of connections to an ActiveMQ message broker (server). In Figure 8-14, the DefaultActiveMQConnectionFactory is a connector to the Geronimo-hosted instance of the ActiveMQ server.


Deploying and Managing Applications

While the Web console has a variety of configuration and management features, the most frequently used feature is undoubtedly the ability to deploy and manage applications and application modules.

More specifically, the Web console has portlets for:

  • Deployment of WAR-, JAR-, and EAR-based components or applications

  • Starting, stopping, and uninstallation of deployed EAR applications

  • Starting, stopping, and uninstallation of deployed WAR applications

  • Starting, stopping, and uninstallation of EJB-based JAR modules

  • Starting, stopping, and uninstallation of J2EE resource adapter (connector) modules

  • Starting, stopping, and uninstallation of J2EE client applications

  • Starting, stopping, and uninstallation of Geronimo system modules

This covers practically everything you would want to do with application modules. It also mirrors all the capabilities of the command-line deployer tool (see Chapter 6).

Deploying Applications

To deploy application modules, select Applications→Deploy New to bring up the Install New Application portlet shown in Figure 8-15.

Image from book
Figure 8-15: The Install New Application portlet

In Figure 8-13, using the Install New Application portlet, you can then browse to the binary module that you want to deploy, and then optionally include a Geronimo-specific deployment plan. Chapter 9 provides a thorough survey of the various deployment plans that you can include when you deploy your module. You can also choose to either start the application running after deployment or leave it in a stopped state. If you check the Start app after install box, the application will be started after deployment.

Table 8-3 enumerates the type of modules that you can deploy and their typical content.

Table 8-3: Module Types and Content Open table as spreadsheet
Module Type | Archive File | Description
Web application | WAR | Web-tier applications containing static resources (Web pages, and so on), servlets, JSP, frameworks, and Java classes.
Enterprise application | EAR | Includes Web-tier applications and business-tier EJBs in separate bundles. Also may contain a resource adapters archive or a client application archive.
EJB JAR | JAR | Collection of business-tier EJBs in a bundle.
Resource Adapter | RAR | A JCA 1.5 resource adapter implementation - typically a JDBC driver or a JMS connector.
Client application | JAR | A client application that makes use of the Geronimo client application container.

When you deploy an application module using the Web console, the equivalent command line using the command-line deployer is:

deploy --user system --password manager deploy <application archive>   [<deployment
plan>]

If you leave the Start app after install checkbox unchecked, the equivalent command line using the command-line deployer is:

deploy --user system --password manager distribute <application archive>
[<deployment plan>]

Once you have the module started, either by using the Web console or the command-line deployer, you should be able to see the JSR-77 state of the module (running, stopped, and so on) next to the component’s name listing on the Web console.

Managing Deployed Modules

After successful deployment, the deployed module should be in running state. Depending on the type of module that is actually deployed, the component will show up on different areas of the Web console. There are six areas:

  • Applications→Application EARs for deployed enterprise applications

  • Applications→Web App WARs for deployed web applications

  • Applications→EJB JARs for deployed standalone EJB archives

  • Applications→J2EE Connectors for deployed resource adapters

  • Applications→App Clients for deployed application clients

  • Applications→System Modules for deployed system modules

Enterprise Applications

If you select Applications→Application EARs from the Web console, the Installed Application EARs portlet will show all the enterprise application EAR files installed on the server. You will also see the JSR-77 state of each module. Figure 8-16 shows the Installed Application EARs portlet.

Image from book
Figure 8-16: Portlet showing all the installed enterprise application EAR modules

In Figure 8-16, you can see that Web console (geronimo/webconsole-tomcat/1.1/car) is installed on this Geronimo server and is currently running. Note that you can do the following:

  1. Click the Stop link to stop a running module

  2. Click the Start link to start a stopped module

  3. Click the Uninstall link to undeploy a stopped module

If you use the command-line deployer instead of the Web console, the corresponding equivalent commands are:

  1. deploy --user system --password manager stop <module id>

  2. deploy --user system --password manager start <module id>

  3. deploy --user system --password manager undeploy <module id >

The module ID is the complete name of the deploy module. For example, the Web console has module ID of geronimo/webconsole-tomcat/1.1/car.

Web Applications

If you select Applications→Web App WARs from the Web console, the Installed Application WAR portlet will display all the Web application WAR files that are deployed. Their module ID will be shown, as well as their JSR-77 state. This portlet is identical in layout and usage as the Installed Application EARs portlet described in the preceding section, “Enterprise Applications.”

EJB JARs

If you select Applications→EJB JARs from the Web console, the Installed EJB JAR portlet will display all the EJB JAR files that are deployed. Their module ID will be shown, as well as their JSR-77 state. This portlet is identical in layout and usage as the Installed Application EARs portlet described in the earlier section “Enterprise Applications.”

J2EE Connectors

If you select Applications→J2EE Connectors from the Web console, the Installed J2EE Connectors portlet will display all the JCA 1.5 connectors that are deployed on the server. Their module ID will be shown, as well as their JSR-77 state. This portlet is identical in layout and usage as the Installed Application EARs portlet described in the earlier section, “Enterprise Applications.”

Client Applications

If you select Applications→AppClients applications from the Web console, the Installed Client Applications portlet will display all the client applications that uses the Geronimo application container and deployed on the server. Their module ID will be shown, as well as their JSR-77 state. This portlet is identical in layout and usage to the Installed Application EARs portlet described in the earlier section “Enterprise Applications.”

System Modules

If you select Applications→System Modules from the Web console, the Installed System Modules portlet will display all the system modules that are deployed on the server. These modules are installed and started by default with the distribution of the Geronimo server. Their module ID will be shown, as well as their JSR-77 state. This portlet is identical in layout and usage as the Installed Application EARs portlet described in the earlier section “Enterprise Applications.”


Working with Geronimo Plug-Ins

Selecting Plugins→Create/Install will take you to the Create and Install Plugins portlet.

Geronimo plug-ins are self-configuring modules that can be downloaded and installed easily. Typically, plug-ins add new features to the Geronimo server. Downloading plug-ins allows you to expand the capabilities of your server only when you need it.

Figure 8-17 shows the Create and Install Plugins portlet.

Image from book
Figure 8-17: Creating, installing, and removing plug-ins

Plug-ins can be downloaded and installed into your Geronimo server with a single click. However, you must first find a Geronimo Plugin repository. In order not to be biased or appear to favor any specific Geronimo plug-in download sites, Geronimo does not come with a default repository.

In the portlet shown in Figure 8-17, you can click the Update Repository List to download the current list of available public Geronimo plug-in repositories. Once the list is updated, it will become available from the drop-down list.

Since plug-ins are actually Geronimo modules, you can uninstall plug-ins in the same way that you uninstall modules. You need to find the plug-in in one of the Applications menu (such as System Modules) and then click the associated Uninstall link.

You can create plug-ins from any of the currently running modules. The portlet allows you to select the modules from a list, and it will create a CAR file from the current configuration of the selected module.

There are situations when creating your own plug-in make sense. As an example, say you manage a farm of Geronimo servers, and you need to deploy and configure the same application to many servers. Instead of performing this manually on each server, you can install and configure the application on one server, then use this server as your own plug-in repository where the other servers can find and install the plug-in.

The downloadable bonus Chapter 17 (www.progeronimo.com) provides details on how to create your own plug-in and set up the Geronimo server as a plug-in repository.


Security Configuration

The security menu contains selections for adding additional users for the console (through the console security realm), for configuring security realms in general (realms are usable by both Geronimo and applications running on Geronimo), and also for configuration of the keystore (the keystore is used to store and maintain security certificates for SSL operations).

Configuration of Console Realm

The console realm maintains group, user, and password information for users of the Web console application.

Security Realm Configuration

The security subsystem in Geronimo is built around the concepts of Login Modules and Security Realms. Chapter 15 has a lot more information on these concepts, For now, think of a security realm as a database for group, user, and password information, used by applications and/or the server itself, during the user authentication process.

When you select Security→Security Realm, you can use the Security Realms portlet to edit an existing security realm, or create a new security realm. Figure 8-18 shows the security realms portlet in action.

Image from book
Figure 8-18: Creating a new security realm with the Security Realms Portlet

Figure 8-18 shows the first screen after clicking Add a New Security Realm. A security realm can be of different types, depending on where it stores and retrieves authentication information. The types supported by Geronimo include:

  • Certificate properties file

  • Database realm (uses a relational database to store and retrieve authentication information)

  • LDAP realm (users LDAP interface typically to a directory service for authentication information)

  • Properties file realm (uses properties file to maintain authentication information - the default realm is of this type)

  • Other custom implementation realm type (developers may take advantage of this for specialized applications)

Chapter 15 features a detailed discussion of the relationship between security realms and login domains, and shows how to use the Security Realm portlet to add new realms or modify existing one.

Keystore Configuration

Geronimo can use a HTTPS listener to receive requests over an encrypted connection. Secured HTTP implementation is based on public key encryption and requires the server to maintain a certificate issued by (usually purchased from) third-party trusted certificate authority (CA), along with the server’s own private key.

The Security→Keystore Configuration menu selection enables you to create a keystore to store your own private key and your certificates. Figure 8-19 shows the portlet.

Image from book
Figure 8-19: Using the Keystore Configuration portlet

In Figure 8-19, there are two keystores, the default keystore and a newly created one called newkeystore.


Embedded Database

Obtaining Database Information

Geronimo includes a built-in relational database. When you select Embedded DB→DB Info, menu, you will receive a screen full of information describing the embedded database.

The database is Apache Derby. It is a 100 percent Java, full-featured relational database that is originally based on code initially contributed by IBM. In fact, IBM continues to market a version of the database called Cloudscape.

Geronimo uses this embedded database as a system database. You can also use this database in your own application. Figure 8-19 shows the page displayed by Geronimo. It provides a lot of useful information on the embedded Derby instance.

Database Manager Portlet

The Database Manager portlet enables you to configure and work with the embedded database instance.

This database instance is used by some Geronimo system services such as ActiveMQ.

Using the database manager portlet, you can create new database instances, create new tables, and execute SQL against the embedded database instance. You can also view tables and their contents in both the application and (Derby) system databases.

Figure 8-20 shows the entry of a SQL CREATE TABLE statement to be executed on the embedded Derby instance.

Image from book
Figure 8-20: Running SQL against the embedded database with Database Manager portlet


Summary

The Geronimo Web console is one of the easiest-to-use administrative tools that Geronimo has to offer. This chapter explored the features of the Web console. You discovered that the console can be used to do the following:

  • View server information, such as memory usage, thread usage in thread pools, Java VM version and system property values

  • Shut down the server

  • Configure Web server, EJB server, and JMS server

  • Deploy, start, and stop various application modules and the system resources module

  • Install additional system resources such as JDBC connectors and JMS connection factories

  • Add binaries to the Geronimo repository

  • Create and install Geronimo plug-ins

  • Maintain security realms that are used serverwide for user authentication and authorization

You have also discovered that many of the Web console’s features duplicate the commands in the deployer tool.

Chapter 9 presents the various deployment plans and deployment descriptors that you can use when deploying application modules and resources.


Chapter 9: Geronimo Deployment Plans

Overview

Binary executable modules are deployed to a Geronimo server through the help of deployment descriptors and deployment plans. Deployment descriptors are mandatory elements of standard J2EE deployable archives, and are J2EE container neutral. Often, standard J2EE deployment descriptors are insufficient to specify everything needed for successful deployment. In these cases, you must create Geronimo-specific deployment plans. All deployment descriptors and plans are XML documents. Depending on the type of binary module being deployed, there are different deployment plans.

This chapter enumerates and explains the different Geronimo deployment descriptors and deployment plans. The coverage includes:

  • The type of modules that each deployment descriptor or deployment plan can be used for

  • The placement of the deployment descriptors and deployment plans

  • The naming of the deployment plan, when deployed external to a module

  • The XML schemas that precisely specify the format of each deployment plan and where you can find them

  • How Geronimo configuration and deployment plans are related

Subsequent chapters describe the deployment of different application modules. Instead of providing details of each deployment plan used in this chapter, references are provided for later chapters where each of the plans is covered in detail.


Deployment Descriptors and Plans

To provide specific handling instructions to the Geronimo server during deployment of a code module, you must include deployment descriptors and deployment plans.

Deployment descriptors and deployment plans are both XML documents, with well-defined syntax, enforced by XML schemas. All of the schemas for Geronimo deployment descriptors and deployment plans are stored in the schema subdirectory of the Geronimo distribution.

Deployment descriptors are in a format specified by the J2EE specifications and are mandatory for compliance. Deployment descriptors are always included as part of the deployed archive.

Deployment plans are in a Geronimo-specific format and are optional when deploying modules. The deployment plan provides additional instructions to the Geronimo server, above and beyond those in the standard deployment descriptor. More specifically, additional information can be provided for the following:

  • External resource references

  • Security configuration

  • Mapping or remapping referenced resource names

  • Access an external EJB, not deployed with the module

  • Dependency on classes not located via J2EE-specified class loader hierarchy

  • Configuration of a JCA resource adapter in the module

The Geronimo Deployable Modules

The different software components that can be deployed in Geronimo include the following:

  • Web-tier applications, with JSP, servlets, JSP tags, tag libraries, framework coding, and so on

  • Business-tier EJBs in JAR bundles

  • Enterprise applications combining both a business-tier EJB JAR and a Web-tier application WAR

  • Connector resources such as JDBC drivers or JMS connection factories

  • Client applications that make use of Geronimo’s client application container

Each of these software components must be bundled in an archive (JAR file) before deployment into Geronimo. For all the J2EE components, a mandatory J2EE deployment descriptor must be included in the archive.

Standard J2EE Deployment Descriptors

Table 9-1 shows all the standard mandatory J2EE deployment descriptors for the deployable software components listed in the preceding section. For each type of component, the type of archive file, and the location plus name of the standard J2EE deployment descriptor are shown.

Table 9-1: Standard J2EE Deployment Descriptors Open table as spreadsheet
Descriptor Deployable | Archive File | Standard J2EE Deployment and Location
Web-tier application (servlet, JSP, JSP tags, frameworks) | WAR | WEB-INF/web.xml
Business-tier EJB bundle | JAR | META-INF/ejb-jar.xml
Enterprise applications (containing both WAR and EJB JARs) | EAR | META-INF/application.xml
J2EE client application | JAR | META-INF/application-client.xml
JCA resource adapters (usually JDBC drivers or JMS connection factories) | RAR | META-INF/ra.xml

All of the deployment descriptors shown in Table 9-1 are mandatory. If you do not have a correctly formatted deployment descriptor at the specified location within the archive, deployment will fail.

The deployment descriptors are XML files, and their syntax is specified in XML schemas. Each XML schema precisely describes and enforces the syntax of each of these descriptors.

Table 9-2 shows the schema for each of the J2EE deployment descriptors. Later chapters will cover the tags and elements contained in these deployment descriptors. Table 9-2 also has a chapter reference, showing where you can find more information on the use of each of the descriptors.

Table 9-2: XML Schema for Each of the J2EE Deployment Descriptors Open table as spreadsheet
J2EE Deployment Descriptor | XML Schema | Chapter Reference
web.xml | web-app_2_4.xsd web-app_2_3.dtd web-app_2_2.dtd | Chapters 10,11
ejb-jar.xml | ejb-jar_2_1.xsd ejb-jar_2_0.dtd ejb-jar_1_1.dtd | Chapter 12
application.xml | application_1_4.xsd application_1_3.dtd application_1_2.dtd | Chapters 10,11,12
application-client.xml | application-client_1_4.xsd application-client_1_3.dtd application-client_1_2.dtd | Chapter 12
ra.xml | connector_1_5.xsd connector_1_0.xsd connector_1_0.dtd | Chapters 13,16

Unlike J2EE deployment descriptors, Geronimo-specific deployment plans are optional when deploying modules into Geronimo. However, unless you are working with very simple application or deployment scenario, you will likely need to create a custom deployment plan.

These deployment plans can either be embedded within the deployed module (typically besides the J2EE deployment descriptor that it extends) can exist externally (completely independent from the deployed module, and only used in conjunction with the module during deployment).

Deployment Plans Naming

When a deployment plan is embedded inside the module, it must have the name specified in the Table 9-3. However, if you are using an external deployment plan, it can have any name you want.

Table 9-3: Location and Name of Plans Placed Inside Deployed Module Open table as spreadsheet
Deployable | Archive File | Geronimo Specific Deployment Plan
Web-tier application (servlet, JSP, JSP tags, frameworks) | WAR | WEB-INF/geronimo-web.xml
Business-tier EJB bundle | JAR | META-INF/openejb-jar.xml
Enterprise applications (containing both WAR and EJB JARs) | EAR | META-INF/geronimo-application.xml
J2EE client application | JAR | META-INF/geronimo-application-client.xml
JCA resource adapters (usually JDBC drivers or JMS connection factories) | RAR | META-INF/geronimo-ra.xml

The following are some best-practice guidelines to consider when determining whether you should place the plan internal to the module or keep it as an external plan.

An internal plan is distributed with the archive but is not easy to modify. An external plan is easier to modify but must be managed with its associated archive file and is an additional piece that must be distributed (and specified during deployment). This complicates the distribution and deployment process.

The tradeoff, therefore, is flexibility in configuration versus distribution and deployment simplicity.

In general, internal plans are better for the following:

  • Situations where you must deploy the same module to a large number of targets with the same configuration

  • Situations where you need maximum flexibility in configuration (such as where you are deploying to a small number of different targets, each requiring some changes in the deployment plan)

Figure 9-1 illustrates the possible locations of the deployment plans.

Image from book
Figure 9-1: Deployment descriptors and deployment plans for modules’ deployment

In Figure 9-1, the two possible locations for a deployment plan are shown. You can use either location when you’re deploying the module using the Web console or the command-line deployment tool.

Deployment Plan Internal to the Module

When you are placing the deployment plans inside a module, they must be placed in specific locations and have specific names for Geronimo to find them. Table 9-3 shows the name that an internally located deployment plans must have.

Each of the plans in Table 9-3 is an XML document with well-defined contents. The possible contents are restricted and enforced by XML schema files. Table 9-4 enumerates the deployment plans and the XML schema associated with each. You can find all of the schema under the schema directory within the Geronimo distribution.

Table 9-4: XML Schema for Geronimo-Specific Deployment Plans Open table as spreadsheet
J2EE Deployment Descriptor | XML Schema | Chapter Reference
web.xml | geronimo-web-1.1.xsd | Chapters 10,11
ejb-jar.xml | openejb-jar-2.1.xsd | Chapter 12
application.xml | geronimo-application-1.1.xsd | Chapters 10,11,12
application-client.xml | geronimo-application-client-1.1.xsd | Chapter 12
ra.xml | geronimo-connector-1.1.xsd | Chapters 13,16

If you are using an external deployment plan when deploying a module, you can name the plan whatever you like. In fact, you will specify the name of the plan to use during deployment.

In the case where there is already an embedded plan in a module, Geronimo will always allow you to override the internal plan with an external deployment plan. This is often useful in repurposing a module without removing the embedded plan in the archive.


The Geronimo Deployment Architecture

As you venture to creation of your own deployment plans for your application modules, it is very helpful to keep the Geronimo deployment architecture in mind. As an administrator, you will need to know how deployed modules are managed by Geronimo and how module IDs are assigned by default.

Deployed Module in the Repository

Figure 9-2 illustrates how the information associated with a deployed module is stored in the repository in Geronimo.

Image from book
Figure 9-2: Deployed modules stored in the repository

In Figure 9-2, you can see that a module deployed into the Geronimo server has the following properties:

  • Its binaries, as well as configuration information, are stored in the repository as artifacts.

  • It is assigned a module ID.

  • All subsequent operations with the module, once deployed, are always via the module ID.

The Geronimo server deals in configuration management. This is, as the name implies, the management of configured modules (grouping of GBeans). As such, the configuration of a module being deployed into the server is turned into a serialized module configuration, and configurations are stored in the repository (see Chapter 6 for more information on how these serialized module configuration files are stored there).

Assignment of Module IDs

The main method of controlling the actual module ID that is used by Geronimo is via the <moduleId> element in the various Geronimo-specific deployment plans. For example, in the geronimo-web.xml deployment plan, the module ID may be declared as follows:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.1">
<environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <moduleId>
      <groupId>com/wrox/progeronimo</groupId>
      <artifactId>progeron</artifactId>
      <version>1.0</version>
      <type>car</type>
    </moduleId>
  </environment>

The highlighted lines in the preceding listing specifies that the module ID for this deployed WAR file should be, in short form: com/wrox/progeronimo/progeron/1.0/car.

If you do not specify the optional modueId in the <environment> element in your Geronimo-specific deployment plan, Geronimo’s deployment code will try its best to create one for you. It will assign the following default moduleId:

<default group>/<basename of your deployed module>/<timestamp>/car

The <default group> for Geronimo 1.1 is default. The base name of your deploy module is the filename without the file extension. For example, the base name for progeron.war is progeron, and for authors.ear is authors. The <timestamp> element, created to stand in as a default version number, reflects the time of deployment expressed as a long integer (64-bit number).


Summary

In this chapter, you explored:

  • The different J2EE-deployable modules for Geronimo

  • The mandatory J2EE deployment descriptors that must be included in the module

  • The optional Geronimo-specific deployment plans that can be included during deployment

The mandatory J2EE deployment descriptors have specific names and must be placed in specific location within the module archive. Their contents are well specified via XML schemas.

The optional Geronimo-specific deployment plans can be placed inside the deployed module or external to the module. When placed internally, they must be at a specific location with a specific name in order for Geronimo to find them. The contents of Geronimo-specific deployment plans are regulated via XML schemas.

Once a module is deployed into Geronimo, it is referenced using a module ID. This module ID can be specified explicitly using a Geronimo-specific deployment plan for the module. By default, Geronimo will use the base name of the archive file and a timestamp to create the default module ID.

Upcoming chapters will guide you through the deployment of all the different types of deployable modules. You will get a chance to explore and work with many deployment descriptors and deployment plans in the examples within these chapters.


Chapter 10: Web Container Configuration and Jetty

Overview

Web applications get the most attention in the Java development arena. Just like the lead singer of the band, the most interactive component gets the brunt of the attention. It is where the end user meets your application and interacts with the back end. Web applications require a servlet/JSP container, often called a Web container. Geronimo provides two proven and certified Web containers: Apache Tomcat and Jetty. Geronimo allows you to run either Jetty or Tomcat simply by downloading the corresponding binary distribution. You can even run both Tomcat and Jetty at the same time with a custom build from source code!

The Geronimo extensions to the standard deployment descriptor, web.xml, allow you to leverage some of the unique extended features of Jetty/Tomcat components. They also allow you to:

  • Set up Geronimo security mappings

  • Set up naming and JNDI environment settings

  • Configure and deploy additional GBeans

This chapter explains how to select a Geronimo Web container to host your applications. It also describes the configuration of a Web application using the Geronimo-specific deployment plan, geronimo-web.xml. The different Web container-specific GBeans that you can configure for your Web application are covered. As with the first of two chapters on configuring Web containers, this chapter will primarily concentrate on the Web descriptor file as it pertains to Jetty and Jetty container GBeans. Tomcat configuration is discussed in detail in Chapter 11.


Web Container - Jetty or Tomcat

Geronimo comes preconfigured with one of two Web containers: either Jetty or Tomcat. Both containers have been fully J2EE 1.4 certified as part of Geronimo.

The GBean architecture and pluggability of its components allows Geronimo to easily adapt to either container. It is even possible to use them both at the same time via a custom build from source code.

Running Both Jetty and Tomcat at the Same Time?

You may be asking why would anyone want to run both containers at the same time in the application server? Most people wouldn’t, and you normally shouldn’t. In nearly all end-user cases, running both containers at the same time will not be a reasonable configuration for Geronimo. There are situations where you may wish to do timings and testing of the different Web containers at the same time, without the need to work with two different set of binaries. Allowing Geronimo to run both containers at the same time, and still remain certified, demonstrates the flexibility of the Geronimo componentized architecture.

Important

This ability to run both containers at the same time was a critical capability during the J2EE 1.4 testing for certification (a very long and tedious process) because it allowed Geronimo to certify both containers by switching the configuration and being able to shut off or disable one container, while the other was being tested. Hence the server did not require a redistribution/deployment of GBeans upon testing the different containers, just a change in the config.xml files.

The config.xml File

The config.xml file holds configurations for manageable attributes of a GBean that allow for customization, relieving you of the need to have to redistribute the GBean plan. Simply by editing this file (when Geronimo is not running), you are able to easily alter the configuration of Geronimo, passing the GBean manageable parameters and telling Geronimo which configuration plans to run. This file is processed by the Geronimo server during startup to determine the GBeans that it will load. Listings 10-1 and 10-2 show examples of the config.xml configurations for the Tomcat and Jetty installations.

Listing 10-1: config.xml Snippet of the Tomcat Container Configuration
Image from book
...
<module name="geronimo/tomcat/1.1/car">
        <gbean name="TomcatWebConnector">
            <attribute name="host">0.0.0.0</attribute>
            <attribute name="port">8080</attribute>
            <attribute name="redirectPort">8443</attribute>
        </gbean>
        <gbean name="TomcatAJPConnector">
            <attribute name="host">0.0.0.0</attribute>
            <attribute name="port">8009</attribute>
            <attribute name="redirectPort">8443</attribute>
        </gbean>
       <gbean name="TomcatWebSSLConnector">
           <attribute name="host">0.0.0.0</attribute>
           <attribute name="port">8443</attribute>
       </gbean>
   </module>
...
Image from book

Listing 10-2 shows how to change the adapter used (in the case where your machine has multiple network adapters), and the port on which the Geronimo server listens. The host address of 0.0.0.0 tells Geronimo to listen to all adapters on the machine.

Listing 10-2: config.xml Snippet Jetty Container Configuration
Image from book
...
<module name="geronimo/jetty/1.1/car">
        <gbean name="JettyWebConnector">
            <attribute name="host">0.0.0.0</attribute>
            <attribute name="port">8080</attribute>
            <attribute name="redirectPort">8443</attribute>
        </gbean>
        <gbean name="JettySSLConnector">
            <attribute name="host">0.0.0.0</attribute>
            <attribute name="port">8443</attribute>
        </gbean>
</module>
...
Image from book

As explained in Chapter 5, each one of the <module> entries in config.xml names a plan configuration. The <gbean> entries correlate to the named GBean component in that plan, and the <attribute> element refers to a configurable attribute on the GBean. These attributes will override the settings in the Jetty and Tomcat configuration plans and will take effect the next time the module or server is restarted. The Jetty GBean and attributes will be explained later in this chapter, and the Tomcat GBeans and attributes will be explained in Chapter 11.

Default Configuration

Depending upon which container you selected to run, the default container will be running on port 8080 for HTTP and 8443 for HTTPS. This is easily changed in the config.xml file, as shown earlier. When you start up the Geronimo server from the command line, you should see the ports that the container is running on:

Booting Geronimo Kernel (in Java 1.4.2_11)...
Module  1/20 geronimo/rmi-naming/1.1/car              started in  1.406s
Module  2/20 geronimo/j2ee-server/1.1/car             started in   .968s
Module  3/20 geronimo/j2ee-security/1.1/car           started in  1.078s
Module  4/20 geronimo/axis/1.1/car                    started in   .078s
Module  5/20 geronimo/openejb/1.1/car                 started in   .375s

...

Startup completed in 47 seconds
Listening on Ports:
  1099 0.0.0.0 RMI Naming
  1527 0.0.0.0 Derby Connector
  4201 0.0.0.0 ActiveIO Connector EJB
  4242 0.0.0.0 Remote Login Listener
  8009 0.0.0.0 Jetty Connector AJP13
  8080 0.0.0.0 Jetty Connector HTTP
  8443 0.0.0.0 Jetty Connector HTTPS
  9999 0.0.0.0 JMX Remoting Connector
 61616 0.0.0.0 ActiveMQ Message Broker Connector

Started Application Modules:
  EAR: geronimo/webconsole-jetty/1.1/car
  RAR: geronimo/activemq/1.1/car
...

In this case, you can see that Jetty is running and it has its HTTP connector running on port 8080 and its HTTPS connector on 8443. The other way to see which container is running is to view the welcome screen. By launching a browser, you can navigate to the following URL, and you should see a screen similar to Figure 10-1:

http://localhost:8080/

Image from book
Figure 10-1: Default welcome screen for Web container

Note that the upper-right corner of the browser screen tells you which container is running on the URL/port combination. In this case, it is Jetty 5.1.10.

Configuring Your Container

There are numerous ways to reconfigure your Web container, and, in Geronimo, it offers three ways. These three ways are, in order of increasing difficulty:

  • Via the Web console

  • Editing the config.xml file

  • Changing the GBeans in your assembly with the source code, and then recompiling/building

The Web console usually comes ready to run if you have downloaded a binary distribution. It is also, by far, the easiest way to reconfigure certain commonly modified attributes of server component GBeans.

Adding Connectors via the Web Console

The console allows you to view, edit, and add connectors to your Web applications. It also allows you to start and stop your Web application from your Web browser. General usage and capabilities of the Web console has been covered in Chapter 8. The following discussion repeats just enough of this coverage to assist those readers who are reading this chapter in isolation. You can start the console with the following:

http://localhost:8080/console

You will be asked to log in. The username is system and the password is manager for a default Geronimo installation. On the left side of the screen is the navigation menu. To view, edit, or add a connector, select the Web Server link under the Server heading, and you should see a screen that lists the connectors for the Web server, as shown in Figure 10-2.

Image from book
Figure 10-2: Network Listeners portlet

Each connector is a listener for request, servicing a specific protocol, and listening on a specific host:port combination. From this portlet, you are able to edit currently installed connectors. You are able to stop a connector, edit a connector’s configuration, remove a connector, or add a new connector. Each one of the links to the right of the connector allows you to stop, edit, or delete the connector. You may add one of three different kinds of connectors: AJP, HTTP, or HTTPS. Adding a connector will offer you the capability to fill in most of the necessary options to make that connector run.

For example, if you wanted to create a new HTTP connector that would listen on port 9090, you would select the Add New HTTP Connector for Jetty link. The Network Listeners portlet will display a screen asking you for necessary information to set up your new HTTP connector, as shown in Figure 10-3.

Image from book
Figure 10-3: Network Listeners portlet for setting up HTTP

The Unique Name is what you will name your connector. This name should be unique across all connectors. In this example, type in MyNewHTTPConnector for the Unique Name. The Host field is the IP address that you want the connector to respond to. If you have multiple LAN adapters on your machine and want a specific network interface to respond, you would type that IP address in this field. However, you will typically want the connector to listen in on all network interfaces or IP addresses. To do this, your Host should contain 0.0.0.0. The Min Threads and Max Threads fields allow you to set the size of the pool of threads, from a minimum and maximum perspective, that the container can handle. If you expect your site to receive a highly concurrent load of users, you would increase these values.

Each of the three types of network connectors will minimally include what was just described for fields. However, the different connector types may ask many more questions for their proper configuration. For example, the HTTPS connector will require more information to set up an SSL configuration. You will need to specify a keystore file, passwords for the keystore and the server, the keystore type, HTTPS algorithm and protocol, and whether client authentication is required (as used for forcing the client to present a valid certificate created by the server). Figure 10-4 shows the fields that are required for the HTTPS connector.

Image from book
Figure 10-4: Network Listeners portlet for setting up HTTPS

Adding Connectors via the config.xml

Adding connectors via the Web console is clearly the simplest method of adding a connector. One of the byproducts of the Web console’s adding a new connector is that it actually adds an entry into the config.xml file. In the last section, you were shown how to add a new HTTP connector to the Jetty Web connector using the console. The console actually added the following configuration to the config.xml file:

...
<module name="geronimo/jetty/1.0/car">
  ...
  <gbean gbeanInfo="org.apache.geronimo.jetty.connector.HTTPConnector"
name="geronimo/jetty/1.1/car?ServiceModule=geronimo/jetty/1.1/car,j2eeType=GBean,
name=MyNewHTTPConnector">
      <attribute name="maxThreads">50</attribute>
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="minThreads">10</attribute>
      <attribute name="port">9090</attribute>
      <reference name="JettyContainer">
        <pattern>
          <groupId>geronimo</groupId>
          <artifactId>jetty</artifactId>
          <version>1.1</version>
         <type>car</type>
         <name>JettyWebContainer</name>
       </pattern>
     </reference>
   </gbean>
  ...
</module>
...

Of course, you can also add new connectors by hand to the config.xml file and add the same text as shown here. The GBean is located by Service Module, j2eeType, and the unique name of the module. The gbeanInfo represents the connector Java object that is being used, and the attributes and references are those that are defined for the Java object. A list of the GBeans/connectors can be found in Tables 10-5, 10-6, and 10-7 for Jetty, later in this chapter, and for Tomcat, they can be found in Chapter 11.


Configuring Web Applications

The Java servlet specification describes a generic configuration of a Web application that allows the Web application to be portable across containers through the use of the web.xml file. This means a packaged WAR file would theoretically be able to be deployed on nearly any application server or Web container without any need to change the configuration or code. However, each application server typically has additional options that can enhance the power of the application through the use of a proprietary configuration file.

Nearly every application server and Web container has a descriptor file that enables you to extend the capabilities and configuration beyond the specification. For example, in standalone Tomcat, the extended configuration is found in the context.xml file; in BEA Weblogic, it is found in the weblogic.xml file; and in standalone Jetty, it is the web-jetty.xml file. Geronimo also allows you to extend the capabilities of your Web application with the geronimo-web.xml file.

Geronimo-Specific Web App Deployment Plan

The geronimo-web.xml file is essentially a plan file that describes the Web application attributes and provides the ability to configure additional GBeans, allowing you to set Geronimo-specific properties to alter the characteristics of the Web application. In this file, you can set generic Web properties, such as the context root, the priority class loader, and set resource and naming references, as well as setup security, JNDI naming, and so on. It also allows you to set container-specific properties that are very specific to the Tomcat or Jetty containers. For example, you would be able to declare such configurations as a Tomcat realm and valve chain, and specify which virtual host the Web application should belong to for which Tomcat’s container would only understand. This file is optional when deploying a WAR file and is only needed if you must set specific properties for the application. However, it is strongly recommended that all Web applications use this file.

The geronimo-web.xml is known as the Web app deployment plan file. It is structured within <web-app> elements and can use the contents of this plan in one of three ways:

  • The geronimo-web.xml file can be included in the WAR file’s /WEB-INF directory and packaged with the WAR. The Geronimo Web builder will find the file upon deployment and process its contents at deploy time.

  • The geronimo-web.xml file can be deployed along with the module binaries, using the command-line deployer. In this case, the deployment plan can be maintained external to binaries of the application.

  • The <web-app> can be embedded in another plan file, such as a geronimo-application.xml file that is part of an EAR.

Which of the options you choose is largely dependent upon how you wish to package and deploy the application. There are positives and negatives to whether you choose to keep your Web descriptor in a geronimo-web.xml and have it part of your archive, or deploy the plan externally. Embedding it in your archive keeps everything together as a single file, and deployment becomes simple because there is no external plan to tell the deployer about. The negative side of this is that if you must change the plan for any reason, you need to unpack/rebuild your archive to embed a new plan file.

Deploying/Undeploying/Starting/Stopping Applications

Deploying Web applications can be performed in several different ways. You can use the command-line deployer script (deploy.sh or deploy.bat) in the bin directory, or type in the full Java command. The following example uses the command-line deployer script and uses an external plan file that contains the <web-app> descriptor. Note that a plan deployed in this way does not have to be named geronimo-web.xml; it can have any name.

deployer deploy myapp.war external-plan.xml

If your Geronimo-specific plan is embedded, it must be named geronimo-web.xml and it must be placed into your WAR file’s WEB-INF directory; otherwise, the Geronimo server will not find it during deployment. For embedded plans in a WAR file, you may deploy it without declaring an external plan as follows:

deployer deploy myapp.war

To undeploy an application using the command-line interface, use the undeploy command, along with the named moduleId of your application. For example, if you have an application with the moduleId set to wrox/MyApp/1.0/car, you would undeploy it with the following:

deployer undeploy wrox/MyApp/1.0/car

Starting and stopping an already deployed application can be handled by using the start and stop commands, along with the named moduleId of your application.

You may also use the console to deploy your applications. The left-side navigation menu of the Web console has a Deploy New link under the Applications heading that will show the Install New Applications portlet, as shown in Figure 10-5.

Image from book
Figure 10-5: Install New Applications portlet of the Web console

This portlet allows you to choose your WAR file, as well as your plan file if you wish you have an external plan to deploy with. You may start and stop your Web applications with the Web App WARs navigation link on the left side of the Web console under the Applications heading. As shown in Figure 10-6, this link will show the Installed Web Applications portlet. From this portlet, you can see the state of your Web applications, and you can stop and start your applications from this screen.

Image from book
Figure 10-6: Installed Web Applications portlet of the Web console

Finally, you may also deploy/undeploy your application by copying it into the deploy directory. This is the hot deploy directory and will deploy/undeploy your applications by copying in or removing them from this directory.

Important

Using the deploy directory is only advised for use during development and testing. In a production environment, you should deploy your applications with the command-line interface or the console. The hot deploy does not allow for external plan files.

Web Descriptor Namespace Versions

The geronimo-web.xml plan comes in one of three different versions: Generic, Tomcat, and Jetty. The version you choose will depend on your deployment goals. Depending on the Web container you are using, you will likely want to choose the Jetty or Tomcat version.

If you wanted your application to be able to remain neutral and be deployed to both Tomcat and Jetty, you could use the generic version. Figure 10-7 shows a comparison of the versions.

Image from book
Figure 10-7: geronimo-web XML Schemas (XSD) for Generic, Jetty, and Tomcat

The Web descriptor version that is used is determined by the default namespace that is declared in the <web-app> element. For example, to declare a plan that is specific to Jetty, the <web-app> element would be declared as follows:

<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/jetty-1.1" />

This declaration will have two consequences. First, it will allow Jetty-specific declarations in the plan, and second, when the plan and application are deployed, it will only be deployed to the Jetty container. Therefore, in a situation where Geronimo was running two containers, Tomcat would not deploy the application declared with a Jetty namespace. Table 10-1 lists the different namespaces that are used when requiring a Web application deployment descriptor to use a specific type.

Table 10-1: <web-app> Namespaces and Their Versions Open table as spreadsheet
Type | Namespace
Generic | xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/web-1.1"
Tomcat | xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.1"
Jetty | xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/jetty-1.1"

Each of the Web application descriptors is generally the same, except that they allow container-specific configuration elements that are only understood by the targeted container.

Table 10-1 lists the three Web application descriptor schemas and the XML namespace that you set to default to enable their use.

The generic descriptor does not have any of the proprietary container declarations that the Tomcat and Jetty versions have, but has a special element named <container-config> that allows you to encapsulate container-specific elements by namespace.

In Listing 10-3, a generic descriptor is shown using both Tomcat and Jetty configurations inside the <container-config> element. Notice that the <tomcat> and <jetty> elements reference a configuration namespace for their respective containers. This is not the same namespace as listed in Table 10-1. These reference only the specific container-only attributes that the other descriptors use. Table 10-2 lists these namespaces.

Listing 10-3: Example Generic geronimo-web.xml Descriptor with Tomcat- and Jetty-Specific Attributes
Image from book
<?xml version="1.0" encoding="UTF-8"?>
<web-app   xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
    xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1">
   <sys:environment>
         <sys:moduleId>wrox/exampleapp/1.0/car</sys:moduleId>
         <sys:dependencies>
             <sys:dependency>
               <sys:moduleId>geronimo/j2ee-server/1.1/car</sys:moduleId>
             </sys:dependency>
           </sys:dependencies>
      </sys:environment>

    <!-- Web Parameters -->
    <context-root>/foobar</context-root>
    <context-priority-classloader>false</context-priority-classloader>

    <!-- Container specific configuration -->
    <container-config>

      <!-- Tomcat Specific Container Declarations -->
      <tomcat xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.0/config">
        <valve-chain>FirstValve</valve-chain>
        <host>www.example.com</host>
        <cross-context/>
      </tomcat>

      <!-- Jetty Specific Container Declarations -->
      <jetty xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/jetty-1.0/config">
        <virtual-host>www.example.com</virtual-host>
      </jetty>
    </container-config>

    <!-  Naming/Ref declarations -->
    <naming:resource-env-ref>
      <naming:ref-name>jms/LogQueue</naming:ref-name>
      <naming:message-destination-link>LoggingQueue</naming:message-destination-link>
    </naming:resource-env-ref>

    <!-  Security declaration -->
    <security-realm-name>geronimo-properties-realm</security-realm-name>
    <security>
      <default-principal>
        <principal
           class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
           name="system"/>
      </default-principal>
      <role-mappings>
        <role role-name="admin">
          <principal
          class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"
          name="admin"
          designated-run-as="true"/>
        </role>
      </role-mappings>
    </security>

    <!-GBean declarations -->
    <gbean name="FirstValve"
        class="org.apache.geronimo.tomcat.ValveGBean">
      <attribute name="className">
        org.apache.catalina.authenticator.SingleSignOn</attribute>
    </gbean>

</web-app>
Image from book
Table 10-2: Container Configuration Namespaces Open table as spreadsheet
Type | Namespace
Tomcat | xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.0/config"
Jetty | xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/jetty-1.0/config"

In Table 10-2, note that the version of these container configuration XSDs remains at 1.0, even with the Geronimo 1.1 release.

Common Elements

The generic, Tomcat, and Jetty Web descriptors all have a set of elements that are common among all three files (see Table 10-3). Since the Web application descriptors are basically plan files, they allow you to declare dependencies, GBeans, set naming parameters, and declare security mappings and a security realm, just as you would be able to in many other plans.

Table 10-3: Common Elements Open table as spreadsheet
Element | Description
<web-container> | References a Web container GBean. This feature allows you to run two Web containers at the same time and tells the Web application to which container to deploy the application. If this is omitted, the Web application will use the default Web container to deploy the application.
<context-root> | The context to which the application will be installed. Typically, it will represent the portion of the URL that represents the application. For example, if you wished your URL to be http://yourserver.com:8080/foobar, the value of this element would be /foobar. Note that if this Web application is part of an EAR file, and the EAR contains an application.xml file with a <context-root> declaration, that one will take precedence over the Web version.
<security-realm-name> | References a known security realm typically declared as a GenericSecurityRealm GBean. This would normally be used in conjunction with a login module. See Chapter 15 for configuration.
<security>...</security> block | Provides for declaring role mapping and default principals. See Chapter 15 for configuration.
<naming:xxx>...</naming:xxx> block | Naming block to allow for referencing EJB, JMS, message destinations, and other references. See Chapter 12 for more information.

Container Specific Elements

The generic descriptor is available so that you can create a single deployable plan that can hold container-specific information. It only has one element that is not available in the other descriptors and is the <container-config> element. As explained previously, this element allows you to declare a block based on a namespace that can contain container-specific values. As of this writing, only the configurations that should be referenced are those that are listed in Table 10-2. Keep in mind that the namespaces listed in Table 10-2 are simply subsets of the Jetty and Tomcat web-app descriptor. They only contain the container-specific entries. Following is an example declaration using a Tomcat and Jetty declaration:

...
<container-config>
    <tomcat xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.0/config">
    ...
    </tomcat>

    <jetty xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/jetty-1.0/config">
    ...
    </jetty>
</container-config>
...

It is not mandatory to have both the <jetty> and <tomcat> blocks. You may use both, one, or none. In fact, if your Web application does not need a Tomcat- or Jetty-specific configuration, the <container-config> element may be left out entirely.

Hiding Classes

Although the class loading group elements were covered in Chapter 12, the <hidden-classes> element needs specific mention here because this will likely become an important part, and be used with your Web descriptor plans.

Geronimo is a server that leverages a lot of Open Source projects to produce a best-in-breed application server. This means it probably will be using a lot of the same libraries that you may be using in your applications (such as Spring or ANTLR). When using different versions of the same libraries issues may arise because of the spec for J2EE class loading. You may find that when you deploy a Web application that has Spring or Hibernate as a dependency, you may get a NoClassDefFound or ClassNotFound exception. This issue has to do with the interactions between the Web class loader and server class loader when accessing the used class.

Geronimo uses ANTLR and it’s a part of the parent class loader. When your applications use Hibernate, which uses ANTLR, you may be packaging ANTLR with your WAR. When your application runs, the class loaders check to see if ANTLR is already loaded, and the answer is yes, because it’s already loaded at the server level. But then, according to the spec, there is supposed to be a degree of isolation between the Web application context and the server context (except for certain spec java.* and javax.* classes-see the Child Delegation Model or more information). However, this is only a recommendation and not a strict rule. There are advantages and disadvantages to this model, so to make it a hardened rule could be limiting.

Therefore, it is not necessary for the server to load the child first (again, except in certain circumstances). So the result is a hybrid of a Child Delegation Model and a Parent Delegation Model competing for control with different visibility. In the real world, this means ANTLR is loaded into the server class loader and the Web instantiation has access to the other libraries. When the Web class loader is asked for something, it will say “Have I loaded this class already?” The unequivocal answer is yes. So, it pulls the class from the parent. However, because of the J2EE spec, the server cannot see the Web app’s resources. So, now, when you ask to use ANTLR, you may be using a different version than the one packaged with your application, and the NoClassDefFound or ClassNotFound exceptions may be thrown.

This is actually a common problem with application servers, and the more widely used a library is, the greater the chance that you may run into this problem. One of the most common problems found in several application servers is the Apache Commons Logging API. This is used by many application servers, and yet, developers will include the Commons Logging JAR and end up receiving many different kinds of exceptions. Some application servers will require you to edit the application classpath to get around these issues, so that there are priorities for what libraries are loaded how and when. Keep in mind, the more popular a particular library is, the greater the chance you will run into this problem with it.

The great news is that Geronimo allows you to do something that few other application servers allow. It allows you to declaratively tell the classloader model to hide certain libraries, thus forcing it to use specific versions. This is even more important when your application uses different versions of JARs than the server. This is a great way to get classloading right, without having to experiment with classpaths for hours or days (and even that may not get you anywhere). Geronimo includes the ability to hide the server classes and force the Web loaders to use their own.

You can do this with the <hidden-classes> element in the <environment> section.

For example, if you had a very common Spring/Hibernate application that you wanted to use in Geronimo, you would find that it clashed with the versions of the Spring and ANTLR libraries that are a part of the Geronimo server. To tell Geronimo to have the classloaders use the versions that you include, use a plan that looks like the following:

<web-app
      xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"
      configId="MyApp">

     <environment>
         <moduleId>wrox/exampleapp/1.0/car</moduleId>
         <dependencies>
             <dependency>
               <moduleId>geronimo/j2ee-server/1.1/car</moduleId>
             </dependency>
          <dependencies>

         <hidden-classes>
             <filter>antlr</filter>
         </hidden-classes>
     <environment>

    <context-root>/</context-root>

</web-app>

In this plan file, you are telling the Web classloader that any packages that start with antlr should not be pulled by the server and it should only see the Web app’s version. This is an elegant solution to a common problem that has been affecting application servers for some time. This gives you a lot of control over the classloaders in a declarative fashion.

One point to take note of is that Geronimo can also do the opposite. You can use the <non-overridable-classes> element to ensure that the server’s version is used and not the Web app’s local copy. Its syntax is the same as the <hidden-classes> element.

Jetty-Specific Elements in geronimo-web.xml

The Jetty-specific elements may be declared as a child to the <web-app> element if it’s used in conjunction with a Jetty descriptor namespace, or as a child of the <container-config><jetty xmlns="..."> block in a generic descriptor. Jetty contains three container-specific elements: <host>, <virtual-host>, and <session-manager>.

<host>

Normally, the connectors will define which host the application will respond to. You may have set up multiple connectors that listen on different IP addresses. Jetty allows you make the applications more fine-grained in responding to requests at a server/host or IP level. By using the <host> element, you may define which real hosts (not virtual hosts) the Web context will respond to. For example, if you wanted your Web application to respond to localhost and 10.0.0.1, then you would add the following configuration to your Web descriptor:

...
<host>localhost</host>
<host>10.0.0.1</host>
...

There is no limit to the number of hosts that you can add to your application.

<virtual-host>

Jetty allows you to declare which DNS names the Web context will respond to. For example, if you wanted your Web application to respond to www.example.com and www.example.net, then you would add the following configuration to your Web descriptor:

...
<virtual-host>www.example.com</virtual-host>
<virtual-host>www.example.net</virtual-host>
...

This is slightly different from the <host> element as shown before. The difference is a virtual-host may represent the same IP address or single host, but you may make the Web application’s response more fine-grained by stating that it will only answer by certain DNS-resolvable names.

There is no limit to the number of virtual hosts that you can add to your application.

<session-manager>

The <session-manager> element allows you to swap out Jetty’s default SessionManager object. This would be used for clustering or creating your own class that handles session management. A possible use is serializing your session objects to a database or flat file. This element will take a fully qualified class name that implements Jetty’s SessionManager interface.


Jetty GBeans

The default setup of the Jetty binary distribution of Geronimo runs in a generic configuration that is appropriate for a development environment. However, when moving to a test or production environment, you will usually want to change the way the server is configured. This can be accomplished by editing the config.xml file when the server is shut down.

Important

When you remove a GBean via the config.xml, you are basically turning it off or stopping it. To do this, you must add a load="false" attribute to the <gbean> element.

This section references most of Jetty’s GBeans that you will likely alter for configuration. Although there are several other Jetty based GBeans, they are typically statically configured in a configuration and need not be altered. Those will not be covered here.

Table 10-4 shows the configurable properties of the JettyContainerImpl GBean - the Jetty container that provides for the central integration of Jetty into Geronimo.

Table 10-4: The JettyContainerImpl GBean Open table as spreadsheet
Type | Name | Req | Description
A | objectName | Yes | This parameter is a string representation of the objectName that is passed from Geronimo automatically when it is created from a plan file and does not need to be declared.
A | collectStatistics | No | true or false. Flag to represent whether the container should collect statistics. Defaults to false.
Legend Type: (A) – Attribute, (R) – Reference to GBean Req: (Yes) – parameter is required, (No) – not required

HTTPConnector (see Table 10-5) is the GBean that provides HTTP type connectors.

Table 10-5: The HTTPConnector GBean Open table as spreadsheet
Type | Name | Req | Description
A | name | Yes | A unique name to identify this connector.
A | protocol | No | The protocol of this connector. May be HTTP only. Defaults to HTTP if not declared.
A | host | No | Which IP address to listen on. If set to 0.0.0.0, then it will listen on all IP addresses. Defaults to 0.0.0.0.
A | port | Yes | Declares which port to listen on.
A | minThreads | No | Minimum number of threads.
A | maxThreads | No | Maximum number of threads or concurrent requests. Defaults to 200.
A | redirectPort | No | Will redirect to the same URL but on the declared port to an SSL connector if web.xml has a security-constraint requiring SSL. Defaults to False.
A | connectUrl | No | Read-only. Returns a string displaying the connector URL.
A | maxIdleTimeMs | No | Maximum time in milliseconds a thread will be attached to a connection without activity.
A | lowThreads | No | The thread count that acts as a threshold for considering the container running with a low thread count. It generally used in conjunction with the lowThreadsMaxIdleTimeMs.
A | lowThreads MaxIdleTimeMs | No | Sets Jetty’s lowResourcePersistTimeMs, which represents the maximum time in milliseconds a thread will be attached to a connection without activity, when the server is low on thread resources. This allows you to change thread-holding behavior when resources are low.
A | acceptQueueSize | No | Maximum size of queue to accept requests before refusing connections. Default is 10.
A | lingerMillis | No | Length of time in milliseconds the sockets will linger. Defaults to -1 (disabled).
A | tcpNoDelay | No | Sets the TCP_NO_DELAY on the sockets. Defaults to True.
A | bufferSizeBytes | No | The input stream buffer size in bytes. Defaults to 2048.
R | JettyContainer | Yes | Named reference to the JettyContainer-Impl GBean.
Legend Type: (A) – Attribute, (R) – Reference to GBean Req: (Yes) – parameter is required, (No) – not required

HTTPSConnector (see Table 10-6) is the GBean that provides a HTTPS type connector and is used primarily for SSL. You may declare multiple connectors per container.

Table 10-6: The HTTPSConnector GBean Open table as spreadsheet
Type | Name | Req | Description
A | name | Yes | A unique name to identify this connector.
A | protocol | No | The protocol of this connector. May be only HTTPS. Defaults to HTTPS if not declared.
A | host | No | Which IP address to listen on. If set to 0.0.0.0, then it will listen on all IP addresses. Defaults to 0.0.0.0.
A | port | Yes | Declares which port to listen on.
A | keystore FileName | No | The path and filename of the keystore file. Relative paths will be relative to $GERONIMO_HOME. Defaults to use the .keystore in the user who is running Geronimo’s home directory.
A | keystore Password | No | The password of the server certificate that is stored in the keystore file.
A | keyPassword | No | The password of the private key.
A | keystoreType | No | The type of keystore file used. Defaults to JKS.
A | algorithm | No | Encoding algorithm. Defaults to SunX509.
A | secureProtocol | No | SSL Protocol used. Defaults to TLS.
A | clientAuthRequired | No | Requires that all SSL connections contain a valid client-side certificate chain. Defaults to False.
A | clientAuthRequested | No | Requests that all SSL connections contain a valid client-side certificate chain. Useful for server-mode-based sockets. Defaults to False.
A | maxThreads | No | Maximum number of threads or concurrent requests. Defaults to 200.
A | minSpareThreads | No | Number of thread created upon starting the connector. This value should be smaller then the maxThreads attribute. Defaults to 4.
A | maxSpareThreads | No | Number of threads in the pool that are unused. Defaults to 50.
A | redirectPort | No | Will redirect to the same URL but on the declared port to an SSL connector if the web.xml has a security-constraint requiring SSL. Defaults to False.
A | connectUrl | No | Read-only. Returns a string displaying the connector URL.
A | maxIdleTimeMs | No | Maximum time in milliseconds a thread will be attached to a connection without activity.
A | lowThreads | No | The thread count that acts as a threshold for considering the container running with a low thread count. It generally used in conjunction with lowThreadsMaxIdleTimeMs.
A | lowThreads MaxIdleTimeMs | No | Sets Jetty’s lowResourcePersistTimeMs, which represents the maximum time in milliseconds a thread will be attached to a connection without activity, when the server is low on thread resources. This allows you to change thread-holding behavior when resources are low.
A | acceptQueueSize | No | Maximum size of queue to accept requests before refusing connections. Default is 10.
A | lingerMillis | No | Length of time in milliseconds the sockets will linger. Defaults to -1 (disabled).
A | tcpNoDelay | No | Sets the TCP_NO_DELAY on the sockets. Defaults to True.
A | bufferSizeBytes | No | The input stream buffer size in bytes. Defaults to 2048.
R | JettyContainer | Yes | Named reference to the JettyContainer GBean.
R | ServerInfo | Yes | Reference to a ServerInfo GBean.
Legend Type: (A) – Attribute, (R) – Reference to GBean Req: (Yes) – parameter is required, (No) – not required

AJP13Connector (see Table 10-7) is the GBean that provides HTTP type connectors.

Table 10-7: The AJP13Connector GBean Open table as spreadsheet
Type | Name | Req | Description
A | name | Yes | A unique name to identify this connector.
A | protocol | No | The protocol of this connector. May be AJP only. Defaults to AJP if not declared.
A | host | No | Which IP address to listen on. If set to 0.0.0.0, then it will listen on all IP addresses. Defaults to 0.0.0.0.
A | port | Yes | Declares which port to listen on.
A | minThreads | No | Minimum number of threads.
A | maxThreads | No | Maximum number of threads or concurrent requests. Defaults to 200.
A | redirectPort | No | Will redirect to the same URL but on the declared port to an SSL connector if the web.xml has a security-constraint requiring SSL. Defaults to False.
A | connectUrl | No | Read-only. Returns a string displaying the connector URL.
A | maxIdleTimeMs | No | Maximum time in milliseconds a thread will be attached to a connection without activity.
A | lowThreads | No | The thread count that acts as a threshold for considering the container running with a low thread count. It generally used in conjunction with lowThreadsMaxIdleTimeMs.
A | lowThreadsMaxIdleTimeMs | No | Sets Jetty’s lowResourcePersistTimeMs, which represents the maximum time in milliseconds a thread will be attached to a connection without activity, when the server is low on thread resources. This allows you to change thread-holding behavior when resources are low.
A | acceptQueueSize | No | Maximum size of queue to accept requests before refusing connections. Default is 10.
A | lingerMillis | No | Length of time in milliseconds the sockets will linger. Defaults to -1 (disabled).
A | tcpNoDelay | No | Sets the TCP_NO_DELAY on the sockets. Defaults to True.
A | bufferSizeBytes | No | The input stream buffer size in bytes. Defaults to 2048.
R | JettyContainer | Yes | Named reference to the JettyContainerImpl GBean.
Legend Type: (A) – Attribute, (R) – Reference to GBean Req: (Yes) – parameter is required, (No) – not required

NCSARequestLog (see Table 10-8) is the standard access logger for Jetty.

Table 10-8: The NCSARequestLog logger GBean Open table as spreadsheet
Type | Name | Req | Description
A | fileName | No | The filename to use. If the filename contains “yyyy_mm_dd”, then the file rolls over nightly and is aged according to the retain Days setting for number of days to hold the log. Default is logged to System.err.
A | logDateFormat | No | The date/time format string to use for logging the date and time (for example - dd/MMM/yyyy:HH:mm:ss ZZZ).
A | logTimeZone | No | Time zone to be used in the log.
A | retainDays | No | If file is rolled over, the number of days to retain the log.
A | extended | No | If file is to use the extended log format. May be True or False.
A | append | No | If log may append to an existing log file. May be True or False.
A | ignorePaths | No | Comma-delimited string of URL paths to ignore in the log.
A | preferProxied ForAddress | No | If present in the header, prefer to log the proxied-for IP address. May be True or False.
R | JettyContainer | Yes | Named reference to the JettyContainer GBean.
R | ServerInfo | Yes | Reference to a ServerInfo GBean.
Legend Type: (A) – Attribute, (R) – Reference to GBean Req: (Yes) – parameter is required, (No) – not required


Summary

The Web container is the most configurable, and frequently reconfigured, component in the Geronimo server (and likely in most J2EE servers). Geronimo comes with two best-in-breed Web containers: Jetty and Apache Tomcat. This chapter explained how to select a Web container and also how to configure the containers. In this chapter, you have seen:

  • Web deployment descriptor and common elements used for Web container configuration

  • Three different descriptor types and associated XML namespaces: Generic, Jetty, and Tomcat

  • Changing the configuration through the config.xml file

  • Jetty GBeans that you can configure

Although this chapter only focused on the Jetty server in Geronimo, Tomcat’s configuration is significantly more complex and will require its own chapter for explanation. Chapter 11 will be dedicated to Tomcat and its configuration within Geronimo.


Chapter 11: Tomcat Web Container Configuration

Overview

Web containers are one of the more popular components of J2EE because they host the user interface for the interaction between the user and the entire application. It is the part of a server that gains the user’s attention since it controls an application’s visual components. Not surprisingly, it also claims the largest developer base.

Because of this, developers and organization place a large degree of their resources on the Web container and often utilize a Web container’s specific extensions and application programming interfaces (APIs). This leads developers and companies to prefer a particular type or implementation of Web container.

The Geronimo developers understood this and included two of the most popular Open Source Web containers in its distribution: Jetty and Tomcat. This offering allows users the choice to work with the container that they are most comfortable with. More importantly, this also allows easy migration to Geronimo for Web applications that may have specific code for a particular container.

In this chapter, you will:

  • Learn about the Tomcat Web container and its configuration in Geronimo

  • Learn how to set up and use Tomcat

  • Learn how to configure and use the Tomcat extensions in Web applications

Let’s begin by learning a bit about enabling and using Tomcat in Geronimo.


Using Tomcat in Geronimo

Geronimo comes in two flavors, one with Jetty and one with Tomcat as the Web container. You select Tomcat by downloading the preconfigured binary Tomcat distribution.

Running and Verifying Tomcat

After downloading and installing the Tomcat binary distribution, you can verify that Tomcat is configured. Navigate to the bin directory and type geronimo run. (or geronimo.sh run for Linux users). You should see output similar to the following:

Booting Geronimo Kernel (in Java 1.4.2_12)...
Module  1/22 geronimo/rmi-naming/1.1/car              started in   .375s
Module  2/22 geronimo/j2ee-server/1.1/car             started in   .703s
Module  3/22 geronimo/j2ee-security/1.1/car           started in   .625s
Module  4/22 geronimo/axis/1.1/car                    started in   .078s
Module  5/22 geronimo/openejb/1.1/car                 started in   .328s
Module  6/22 geronimo/system-database/1.1/car         started in  3.031s
Module  7/22 geronimo/activemq-broker/1.1/car         started in  2.203s
Module  8/22 geronimo/activemq/1.1/car                started in   .641s
Module  9/22 geronimo/tomcat/1.1/car                  started in  1.781s
Module 10/22 geronimo/geronimo-gbean-deployer/1.1/car started in   .360s
Module 11/22 geronimo/j2ee-deployer/1.1/car           started in   .531s
Module 12/22 geronimo/openejb-deployer/1.1/car        started in   .313s
Module 13/22 geronimo/client-deployer/1.1/car         started in   .063s
Module 14/22 geronimo/axis-deployer/1.1/car           started in   .078s
Module 15/22 geronimo/sharedlib/1.1/car               started in   .016s
Module 16/22 geronimo/tomcat-deployer/1.1/car         started in   .094s
Module 17/22 geronimo/welcome-tomcat/1.1/car          started in   .203s
Module 18/22 geronimo/webconsole-tomcat/1.1/car       started in  3.031s
Module 19/22 geronimo/remote-deploy-tomcat/1.1/car    started in   .203s
Module 20/22 geronimo/hot-deployer/1.1/car            started in   .375s
Module 21/22 default/progeron/1152708461781/car       started in   .437s
Module 22/22 geronimo/jsp-examples-tomcat/1.1/car     started in   .421s
Startup completed in 20 seconds
  Listening on Ports:
    1099 0.0.0.0 RMI Naming
    1527 0.0.0.0 Derby Connector
    4201 0.0.0.0 ActiveIO Connector EJB
    4242 0.0.0.0 Remote Login Listener
    8009 0.0.0.0 Tomcat Connector AJP
    8080 0.0.0.0 Tomcat Connector HTTP
    8443 0.0.0.0 Tomcat Connector HTTPS
    9999 0.0.0.0 JMX Remoting Connector
   61616 0.0.0.0 ActiveMQ Message Broker Connector

Geronimo Application Server started
...

The connectors on ports 8009, 8080, and 8443 signify that the Tomcat Apache JServ Protocol (AJP), HTTP, and HTTPS connectors are listening for Web-based traffic. Now you want to use the browser to verify that Tomcat is serving Web requests. Open up a Web browser and type http://localhost:8080 into the address area of the browser, and you should see the welcome screen, as shown in Figure 11-1.

Image from book
Figure 11-1: Geronimo/Tomcat Welcome Screen

In Figure 11-1, note the Tomcat 5.5.15 identification in the top-right corner. This welcome screen is a visual representation that Tomcat is enabled and running in Geronimo. Now that Tomcat is enabled properly, the next step is learning about configuring Tomcat and customizing its options in Geronimo.


Configuring Tomcat

The Tomcat configuration that comes with Geronimo is a generic arrangement. It is a typical development setup where the connectors listen on port 8080 for HTTP, 8443 for HTTPS utilized with a test Secure Sockets Layer (SSL) certificate, an AJP connector on port 8009, and a JAAS Security Realm that works with the default geronimo-properties-realm security service. This will fit the needs for a majority of developers but will likely need changing when you are ready to move to a production environment. When moving to production, you will likely need to change the security, change the ports that Tomcat will respond to, set up a valid SSL certificate, respond to certain addresses, or implement custom Valves to do specialized logging and other server-specific tasks. Therefore, the server configuration of Tomcat will need to be changed.

Before examining the intricacies of these configuration files, let’s take a look at the Tomcat architecture to help show how the components are put together, which will help define the configuration.

Tomcat Architecture Overview

No matter in which format Tomcat is configured (whether as a standalone server or as a part of Geronimo), its general architecture is the same. Although there are some slight differences between standalone Tomcat and its integration into Geronimo, conceptually they are identical. The main difference in the Tomcat standalone versus Geronimo integration is that some of the Tomcat objects are not needed since other Geronimo services fill the need (such as Naming or Reference declarations). But for the most part, the object hierarchy in both implementations is essentially the same. For the sake of simplicity, this section provides an overview of the portion of the Tomcat architecture that affects the Geronimo integration.

Tomcat components are very object-oriented in nature. Certain objects can contain other types of objects and have a particular hierarchy attached to them, as well as inheritance. For example, in Tomcat, the Server is the top-level object from which everything else becomes a child. In Geronimo, this Server is known as the Container or TomcatContainer. The Container may contain an Engine, and the Engine may have one or more Host objects. Each Host may have multiple Contexts (Web applications). The Container has listeners called Connector objects, which are used to process different kinds of requests. Each Connector can be configured to listen to a particular type of protocol or port (such as HTTP on port 8080, AJP on port 8009, or HTTPS on port 8443). This may seem complicated, but the relationships are clarified visually in Figure 11-2.

Image from book
Figure 11-2: Tomcat/Geronimo object hierarchy

A more pragmatic way of looking at this is that the Engine object handles the entire server. The Engine can have multiple Hosts. A server would want to have multiple Host objects if it had to implement virtual hosts. For example, one Host object could handle requests to a particular address such as localhost, where another Host object would handle requests to www.wiley.com. This allows a single server to serve multiple Web applications for different Web addresses. To take this a step further, each Host should be able to have multiple Web applications and thus can have multiple Context objects.

The more interesting part of this architecture is the inheritance of the Realm and Valve objects. How the inheritance works for each of these objects is slightly different. The Realm objects are typically used for security and can be applied at the server level (Engine), the Host level, or the Web application (Context) level. If a Realm is not attached at a particular level, then it uses its parent. If the parent does not have one, then the grandparent’s version is used. This allows you to declare security at any level and have the children inherit and use that security. If you want to change it for a particular Host or Context, you can have that level set a Realm and it will be used instead.

The Valves are interceptor objects that allow you to work with the requests and responses before Tomcat (at the different levels) handles them. They are kind of like a deep filter. They are used for things such as specialized logging or click-through analysis, or single-sign-on (SSO). The Valves at the different levels, however, are not replacing parents, but instead are adding on to the parental Valves. Therefore, a company may wish to have all its applications log each request in detail, but a single application use SSO. In this scenario, a logging Valve would be applied at the Engine level, and the SSO Valve would be applied at the Context level. This application would then log its requests and implement SSO.

Having an understanding the Tomcat architecture will help with configuring the Web container, since the setup of the Geronimo configuration files mirror the architecture.

Geronimo Tomcat Configuration

Configuring Tomcat in Geronimo follows a similar paradigm as you would with just Tomcat alone, where you edit XML files to tell the Web container which objects and attributes to use and how to run the server. Tomcat, on its own, primarily uses two XML files for configuration: server.xml for server level and context.xml for Web application level configuration. However, in Geronimo, these files do not exist in the Tomcat format but instead exist in plan configuration XML files as GBeans.

Table 11-1 shows a comparison of Tomcat configuration files with Geronimo equivalents.

Table 11-1: Tomcat Configuration Files and Their Geronimo Equivalents Open table as spreadsheet
Tomcat File | Geronimo File | Description
server.xml | Tomcat configuration plan.xml from the source code (or var/config/config.xml for overriding attributes of the preconfigured GBeans) | Provides for configuring the server, such as the Engine, Host, Connectors, Realms, and Valves.
context.xml | geronimo-web.xml | Allows configuration of Web-application-level attributes such as context roots, and Web-application-level Valves and Realms.

For those who are familiar with Tomcat’s configuration files, the server.xml file’s equivalent can be found in the source code $GERONIMO_SOURCE_HOME/configs/tomcat/src/plan/plan.xml file. Even without source code access, the configuration in plan.xml can be changed and altered with the GERONIMO_HOME/var/config/config.xml file by adding GBean configurations or overriding GBeans’ attributes. The context.xml file’s equivalent is the geronimo-web.xml file that was discussed in Chapter 10 and later in this chapter. The geronimo-web.xml is a Geronimo-specific deployment plan that is used when deploying your Web application.

If you are changing the server configuration from the Geronimo source code, you only need to edit the $GERONIMO_SOURCE_HOME/configs/tomcat/src/plan/plan.xml file and rebuild the configuration and j2ee-tomcat-server assembly (see Chapter 18 on the companion Web site). Or, if using the binary, you can alter the GERONIMO_HOME/var/config/config.xml and override or shut off GBeans.

Geronimo’s Tomcat plan.xml

In Tomcat’s standalone container, you would configure the server through the server.xml file. This file sets all the major aspects of the Tomcat server and how it runs. This file will allow you to declare your Engine, Connectors, Hosts, Realms, and Valves. It follows the Tomcat architecture exactly as described earlier in this chapter. Listing 11-1 shows a skeleton server.xml file for standalone Tomcat. This file listing is not complete and has most attributes removed to emphasize the structure. Notice how the XML organization mirrors the Tomcat architecture along with the parent/child relationships.

Listing 11-1: Tomcat’s server.xml Skeleton File Layout
Image from book

<Server>
  <Service name="Catalina">
    <Connector/>
    <Connector/>
    <Engine name="Catalina">
      <Realm/>
      <Valve/>
      <Valve/>
      <Host>
        <Realm/>
        <Valve/>
        <Valve/>
      </Host>
      <Host>
    </Engine>
  </Service>
</Server>
Image from book

In Geronimo, the source code contains the plan.xml file that is the equivalent of the server.xml file. Although you will likely not be using the Geronimo source code, this file is explained here since it is what is ultimately used to create the Tomcat configuration archive (CAR), and it shows the GBeans that you would use to override in the config.xml. You will notice that Geronimo’s Tomcat configuration is based on GBeans and uses GBean wrapper objects in a similar relationship as in Listing 11-1, following the Tomcat architecture.

Although the XML layout is significantly different from the server.xml file, the architecture remains the same. In the plan.xml file, the GBeans use references to other GBeans to show relationships, instead of parent/child XML. They also have attributes to set object specific values. One of the most important attributes on the Tomcat GBeans is the initParams attribute. Since most of the Tomcat GBeans are just wrappers to the actual Tomcat objects, the initParams attribute allows you to set the actual name-value attributes that you would have set in Tomcat’s server.xml. To more clearly show how the initParams attribute works, let’s look at how the Tomcat Host object would be declared in a server.xml file and make note of the attributes (in bold):

<Host name="localhost" appBase="" workDir="work"/>

Now, let’s juxtapose this with a Geronimo Host declaration, making note of the initParams attribute.

<gbean name="TomcatHost"
       class="org.apache.geronimo.tomcat.HostGBean">
  <attribute name="className">org.apache.catalina.core.StandardHost</attribute>
  <attribute name="initParams">
      name=localhost
      appBase=
      workDir=work
  </attribute>
</gbean>

Notice the attributes of the Host in the server.xml now become name-value pairs in the initParams attribute in the plan.xml. So, it is simple to understand how the Tomcat objects are used with GBeans and configured the Geronimo plan file. Examining the plan.xml file will help you to better understand the relationships between the different Tomcat GBeans and their configurations.

Listing 11-2 shows the snippet from the Tomcat plan.xml as it is represented in the source and what constitutes the Tomcat CAR. Notice that the relationships between the GBeans are represented the same way they would be represented in server.xml.

Listing 11-2: Geronimo’s Tomcat Configuration plan.xml Snippet
Image from book

...
   <!-- The following is the equivalent of the server.xml file, but done with
GBeans -->

    <!-- The TomcatContainer/Service -->
    <gbean name="TomcatWebContainer"
class="org.apache.geronimo.tomcat.TomcatContainer">
        <attribute name="catalinaHome">var/catalina</attribute>
        <reference name="EngineGBean">
            <name>TomcatEngine</name>
        </reference>
        <reference name="ServerInfo">
            <name>ServerInfo</name>
        </reference>
        <reference name="WebManager">
            <name>TomcatWebManager</name>
        </reference>
    </gbean>

    <gbean name="TomcatWebConnector"
class="org.apache.geronimo.tomcat.ConnectorGBean">
        <attribute name="name">HTTP</attribute>
        <attribute name="host">localhost</attribute>
        <attribute name="port">8080</attribute>
        <attribute name="maxHttpHeaderSizeBytes">8192</attribute>
        <attribute name="maxThreads">150</attribute>
        <attribute name="minSpareThreads">25</attribute>
        <attribute name="maxSpareThreads">75</attribute>
        <attribute name="hostLookupEnabled">false</attribute>
        <attribute name="redirectPort">8453</attribute>
        <attribute name="acceptQueueSize">100</attribute>
        <attribute name="connectionTimeoutMillis">20000</attribute>
        <attribute name="uploadTimeoutEnabled">false</attribute>
        <reference name="TomcatContainer">
            <name>TomcatWebContainer</name>
        </reference>
    </gbean>

    <gbean name="TomcatAJPConnector"
class="org.apache.geronimo.tomcat.ConnectorGBean">
        <attribute name="protocol">AJP</attribute>
        <attribute name="name">AJP</attribute>
        <attribute name="host">localhost</attribute>
        <attribute name="port">8019</attribute>
        <attribute name="hostLookupEnabled">false</attribute>
        <attribute name="redirectPort">8453</attribute>
        <reference name="TomcatContainer">
            <name>TomcatWebContainer</name>
        </reference>
    </gbean>

    <!-- SSL support
    NOTE: If keystoreFile is a relative path, it is relative to GERONIMO_HOME
    -->
    <gbean name="TomcatWebSSLConnector"
class="org.apache.geronimo.tomcat.HttpsConnectorGBean">
        <attribute name="name">HTTPS</attribute>
        <attribute name="host">localhost</attribute>
        <attribute name="port">8453</attribute>
        <attribute name="maxHttpHeaderSizeBytes">8192</attribute>
        <attribute name="maxThreads">150</attribute>
        <attribute name="minSpareThreads">25</attribute>
        <attribute name="maxSpareThreads">75</attribute>
        <attribute name="hostLookupEnabled">false</attribute>
        <attribute name="acceptQueueSize">100</attribute>
        <attribute name="uploadTimeoutEnabled">false</attribute>
        <attribute name="clientAuthRequired">false</attribute>
        <attribute name="algorithm">Default</attribute>
        <attribute name="secureProtocol">TLS</attribute>
        <attribute name="keystoreFileName">var/security/keystores/geronimo-
default</attribute>
        <attribute name="keystorePassword">secret</attribute>
        <reference name="TomcatContainer">
            <name>TomcatWebContainer</name>
        </reference>
        <reference name="ServerInfo">
            <name>ServerInfo</name>
        </reference>
    </gbean>

    <!-- Engine -->
    <gbean name="TomcatEngine" class="org.apache.geronimo.tomcat.EngineGBean">
        <attribute
name="className">org.apache.geronimo.tomcat.TomcatEngine</attribute>
        <attribute name="initParams">
            name=Geronimo
        </attribute>
        <reference name="DefaultHost">
            <name>TomcatHost</name>
        </reference>
        <references name="Hosts">
            <pattern>
               <type>Host</type>
            </pattern>
        </references>
        <reference name="RealmGBean">
            <name>TomcatJAASRealm</name>
        </reference>
        <reference name="TomcatValveChain">
            <name>FirstValve</name>
        </reference>
        <dependency>
            <name>TomcatResources</name>
        </dependency>

    </gbean>

    <gbean name="TomcatAccessLogManager"
class="org.apache.geronimo.tomcat.TomcatLogManagerImpl">
        <reference name="ServerInfo">
            <name>ServerInfo</name>
        </reference>
        <references name="LogGBeans">
            <pattern>
               <name>FirstValve</name>
            </pattern>
        </references>
    </gbean>

    <!-- Valve -->
    <gbean name="FirstValve" class="org.apache.geronimo.tomcat.ValveGBean">
        <attribute
name="className">org.apache.catalina.valves.AccessLogValve</attribute>
        <attribute name="initParams">
            prefix=localhost_access_log.
            suffix=.txt
            pattern=common
        </attribute>
    </gbean>

    <!-- Realm -->
    <!-- This is an example TomcatJAASRealm -->
    <gbean name="TomcatJAASRealm" class="org.apache.geronimo.tomcat.RealmGBean">
        <attribute
name="className">org.apache.geronimo.tomcat.realm.TomcatJAASRealm</attribute>
        <attribute name="initParams">

userClassNames=org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal

roleClassNames=org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal
        </attribute>
    </gbean>

    <!-- Host -->
    <gbean name="TomcatHost" class="org.apache.geronimo.tomcat.HostGBean">
        <attribute
name="className">org.apache.catalina.core.StandardHost</attribute>
        <attribute name="initParams">
            name=localhost
            appBase=
            workDir=work
        </attribute>
    </gbean>

...
Image from book

Configuring Tomcat

You just saw how the Geronimo Tomcat configuration plan.xml file is similar to a server.xml. But in standalone Tomcat, you would edit the server.xml file directly. Although you could edit the source plan file and rebuild the configuration and assembly, this is not necessary to change the Tomcat configuration. You can override the Tomcat configuration through the config.xml. By simply overriding the attributes and references of the GBeans as they are shown in plan.xml in Listing 11-2, you can alter the Tomcat configuration. For example, to add the jvmRoute parameter to the Tomcat Engine (used for clustering), you would add the following:

...
<module name="geronimo/tomcat/1.1/car">
    ...
    <gbean name="TomcatEngine">
        <attribute name="initParams">
            name=Geronimo
            jvmRoute=node1
      </attribute>
    </gbean>
    ...
</module>
...

Here you are adding the jvmRoute to the initParams attribute on the TomcatEngine GBean. You will notice that the name=Geronimo was included here as well. It is important to note that when overriding the initParams attribute, you should declare all of the same items as in plan.xml for the GBean. This is because the initParams attribute is actually a single attribute, and you are adding the list of Tomcat-specific settings to this attribute. Thus, as you omit a setting, it will not be configured.

In another example, you may not want Geronimo to use the SSL connector for Tomcat. Setting the load="false" attribute for the TomcatWebSSLConnector will prevent it from attaching to the container and running.

...
<module name="geronimo/tomcat/1.1/car">
    ...
    <gbean name="TomcatWebSSLConnector" load="false"/>
    ...
</module>
...

Also, to add a new GBean, you would simply declare the GBean in the configuration. For example, to add a new connector named MyNewHTTPListener that will listen on port 9090, your config.xml would contain the following:

...
<module name="geronimo/tomcat/1.1/car">
    ...
        <gbean
name="geronimo/tomcat/1.1/car?ServiceModule=geronimo/tomcat/1.1/car,j2eeType=GBean,
name=TomcatWebConnector-HTTP-MyNewHTTPListener"
gbeanInfo="org.apache.geronimo.tomcat.ConnectorGBean">
      <attribute name="protocol">HTTP</attribute>
      <attribute name="host">0.0.0.0</attribute>
      <attribute name="port">9090</attribute>
      <attribute name="name">MyNewHTTPListener</attribute>
      <reference name="TomcatContainer">
        <pattern>
          <groupId>geronimo</groupId>
          <artifactId>tomcat</artifactId>
          <version>1.1</version>
          <type>car</type>
          <name>TomcatWebContainer</name>
        </pattern>
     </reference>
    </gbean>
    ...
</module>
...

In this example, the required attributes for the GBean are declared with the necessary values. Notice that when declaring a new GBean, the name must be fully qualified for the naming conventions for a JSR-88 naming convention. This includes the domain name (usually geronimo.server), followed by a “:”, then the Application (null if not part of an application), Module (usually the tomcat CAR), J2EEServer (usually geronimo), j2eeType, and the unique name of the module. The gbeanInfo represents the Java object that is being used, and the attributes and references are those that are defined for the GBean Java object. In this example, it is using the ConnectorGBean.

Hence, you are able override, remove or add GBeans to alter your Tomcat configuration through the config.xml file. Table 11-2 shows a complete listing of each of the Tomcat GBean objects, along with their attributes and references.

Table 11-2: Tomcat GBeans Open table as spreadsheet
GBean Object/Description | Type | Name | Req | Description
TomcatContainer |  |  |  |
The Tomcat container that provides for the central integration of Tomcat into Geronimo. |  |  |  |
 | A | catalinaHome | No | Tells the Web container where it can find the configuration files. Defaults to $GERONIMO_HOME/var/catalina. Recommended that it not be changed.
 | R | EngineGBean | Yes | Refers to the name of an EngineGBean.
 | R | ServerInfo | Yes | Reference to a ServerInfo GBean.
ConnectorGBean |  |  |  |
GBean that wraps the Tomcat Connector object. Allowed for HTTP and AJP type connectors. May declare multiple connectors per container. |  |  |  |
 | A | name | Yes | A unique name to identify this connector.
 | A | protocol | No | The protocol of this connector. May be HTTP or AJP. Defaults to HTTP if not declared.
 | A | host | No | Which IP address to listen on. If set to 0.0.0.0, then it will listen on all IP addresses. Defaults to 0.0.0.0.
 | A | port | Yes | Declares which port to listen on.
 | A | maxHttpHeader SizeBytes | No | The maximum size of an HTTP header request in bytes. Defaults to 4096.
 | A | maxThreads | No | Maximum number of threads or concurrent requests. Defaults to 200.
 | A | maxPostSize | No | Maximum size the connector will accept from a POST operation. Defaults to 2097152 (2MB). May be disabled if the value is less than or equal to 0.
 | A | maxSavePostSize | No | Maximum size the connector will accept from a POST operation that will be buffered by form or client-certificate authentication. Defaults to 4096K. May be disabled with a −1 as the value.
 | A | minSpareThreads | No | Number of thread created upon starting the connector. This value should be smaller then the maxThreads attribute. Defaults to 4.
 | A | maxSpareThreads | No | Number of threads in the pool that are unused. Defaults to 50.
 | A | hostLookup Enabled | No | Forces a DNS lookup when dealing with IP addresses internally. Defaults to False.
 | A | redirectPort | No | Will redirect to the same URL but on the declared port to an SSL connector if the web.xml has a security constraint requiring SSL. Defaults to False.
 | A | acceptQueueSize | No | Maximum size of queue to accept requests before refusing connections. Default is 10.
 | A | connection TimeoutMillis | No | Amount of time in milliseconds to wait for the HTTP request to occur before timing out. Default is 60000.
 | A | uploadTimeout Enabled | No | Allows a longer timeout for uploading data. Defaults to True.
 | A | lingerMillis | No | Length of time in milliseconds the sockets will linger. Defaults to -1 (disabled).
 | A | tcpNoDelay | No | Sets the TCP_NO_DELAY on the sockets. Defaults to True.
 | A | bufferSizeBytes | No | The input stream buffer-size in bytes. Defaults to 2048.
 | A | connectUrl | No | Read-only. Returns a string displaying the connector URL.
 | R | TomcatContainer | Yes | Named reference to the TomcatContainer GBean.
HttpsConnectorGBean |  |  |  |
GBean that wraps the Tomcat Connector object for HTTPS type connectors. Allowed for only HTTPS type connectors and is used primarily for SSL. May declare multiple connectors per container. |  |  |  |
 | A | name | Yes | A unique name to identify this connector.
 | A | protocol | No | The protocol of this connector. May be HTTP or AJP. Defaults to HTTP if not declared.
 | A | host | No | Which IP address to listen on. If set to 0.0.0.0, then it will listen on all IP addresses. Defaults to 0.0.0.0.
 | A | port | Yes | Declares which port to listen on.
 | A | keystoreFileName | No | The path and filename of the keystore file. Relative paths will be relative to $GERONIMO_HOME. Defaults to use the .keystore in the user who is running Geronimo’s home directory.
 | A | keystorePassword | No | The password of the server certificate that is stored in the keystore file. Defaults to "changeit".
 | A | keystoreType | No | The type of keystore file used. Defaults to JKS.
 | A | truststore FileName | No | The path and filename of the truststore file. Relative paths will be relative to $GERONIMO_HOME.
 | A | truststore Password | No | The password of the truststore file.
 | A | truststoreType | No | The type of truststore file used. Defaults to JKS.
 | A | algorithm | No | Encoding algorithm. Defaults to SunX509.
 | A | secureProtocol | No | SSL Protocol used. Defaults to Transport Layer Security (TLS).
 | A | clientAuth Required | No | Requires that all SSL connections contain a valid client-side certificate chain. Defaults to False.
 | A | maxHttpHeader SizeBytes | No | The maximum size of an HTTP header request in bytes. Defaults to 4096.
 | A | maxPostSize | No | Maximum size the connector will accept from a POST operation. Defaults to 2097152 (2MB). May be disabled if the value is less than or equal to 0.
 | A | maxSavePostSize | No | Maximum size the connector will accept from a POST operation that will be buffered by form or client-certificate authentication. Defaults to 4096K. May be disabled with a −1 as the value.
 | A | maxThreads | No | Maximum number of threads or concurrent requests. Defaults to 200.
 | A | minSpareThreads | No | Number of threads created upon starting the connector. This value should be smaller then the maxThreads attribute. Defaults to 4.
 | A | maxSpareThreads | No | Number of threads in the pool that are unused. Defaults to 50.
 | A | hostLookupEnabled | No | Forces a DNS lookup when dealing with IP addresses internally. Defaults to False.
 | A | redirectPort | No | Will redirect to the same URL, but on the declared port to an SSL connector if the web.xml has a security-constraint requiring SSL. Defaults to False.
 | A | acceptQueueSize | No | Maximum size of queue to accept requests before refusing connections. Default is 10.
 | A | connection TimeoutMillis | No | Amount of time in milliseconds to wait for the HTTP request to occur before timing out. Default is 60000.
 | A | uploadTimeout Enabled | No | Allows a longer timeout for uploading data. Defaults to True.
 | A | lingerMillis | No | Length of time in milliseconds the sockets will linger. Defaults to -1 (disabled).
 | A | tcpNoDelay | No | Sets the TCP_NO_DELAY on the sockets. Defaults to True.
 | A | bufferSizeBytes | No | The input stream buffer-size in bytes. Defaults to 2048.
 | A | connectUrl | No | Read-only. Returns a string displaying the connector URL.
 | R | TomcatContainer | Yes | Named reference to the TomcatContainer GBean.
 | R | ServerInfo | Yes | Reference to a ServerInfo GBean.
EngineGbean |  |  |  |
Wrapper for a Tomcat Engine object. It will typically wrap a TomcatEngine object, as declared by the className attribute, which is an extension of the Tomcat org.apache.catalina.core.StandardEngine. |  |  |  |
 | A | className | Yes | A string representation of the underlying Tomcat Engine object. It is highly recommended to only use the org.apache.geronimo.tomcat.Tomcat-Engine object since it supports several functions in Geronimo.
 | A | initParams | Yes | Name-value pair list for attributes specific to the Engine object as described by the className. Each of the name-value parameters are separated by an ‘=’ sign. Should have the name and default Host name-values set. The name value should match a GeronimoSecurityRealm GBean’s realmName attribute to allow security at the Engine level. See the Jakarta Tomcat documentation for a list of specific parameters for the Engine object.
 | R | DefaultHost | Yes | The name of the HostGBean that represents the default host of the container.
 | R | Hosts | Yes | Tells the EngineGbean the naming convention of the HostGbeans. This parameter is set as geronimo.server:j2eeType=Host,* and typically should not be changed. Although this is not a required attribute, the EngineGBean will not find HostGBean objects without it, so it is highly recommended.
 | R | RealmGBean | No | Reference to a RealmGbean that will be applied at the Engine level and normally will cover security for the entire Tomcat container.
 | R | TomcatValveChain | No | Reference to the first Valve in a chain of 1 or more valves that will be applied at the Engine level.
 | R | CatalinaCluster | No | Reference to a Catalina-ClusterGBean that will provide for clustering the TomcatContainer. Clustering GBeans are beyond the scope of this chapter.
 | R | Manager | No | Reference to the name of a ManagerGBean or object extending the ManagerGBean. Used for swapping out the session manager for Tomcat.
HostGBean |  |  |  |
Wrapper for a Tomcat Host object. It will typically wrap a org.apache.catalina.core.StandardHost object, as declared by the className attribute. Multiple HostGbean objects may be declared and each HostGBean will represent a virtual host as defined by the initParams attribute’s name value. |  |  |  |
 | A | className | Yes | A string representation of the underlying Tomcat Host object. It is highly recommended to only use the org.apache.catalina.core.StandardHost object or one that is derived from it.
 | A | initParams | Yes | Name-value pair list for attributes specific to the object as described by the className. Each of the name-value parameters is separated by an ‘=’ sign. Should have the name value set. The name value is a valid network name such as localhost or www.example.com. Keep in mind that a GeronimoSecurityRealm GBean’s realmName attribute should match the name value to allow security at the Host level. See the Jakarta Tomcat documentation for a list of specific parameters for the Host object.
 | A | aliases | No | Comma-delimited list of network aliases that this host will respond to.
 | R | RealmGBean | No | Reference to a RealmGbean that will be applied at the Host level and normally will cover security for the contexts that are under the host. Leaving this blank will default the host to inherit the Engine’s security.
 | R | TomcatValveChain | No | Reference to the first Valve in a chain of 1 or more valves that will be applied at the Host level. This will add on to the chain of any Valves that were declared at the Engine level.
 | R | CatalinaCluster | No | Reference to a Catalina-ClusterGBean that will provide for clustering the TomcatContainer. Clustering GBeans are beyond the scope of this chapter.
 | R | Manager | No | Reference to the name of a ManagerGBean or object extending the ManagerGBean. Used for swapping out the session manager for Tomcat.
ManagerGBean |  |  |  |
GBean wrapper for Tomcat Manager objects. The manager objects allow for changing the session manager for the Tomcat container. |  |  |  |
 | A | className | Yes | A string representation of the underlying Tomcat Manager object. The class name should reference an object that implements the org.apache.catalina.Manager interface.
 | A | initParams | No | Name-value-pair list for attributes specific to the object as described by the className. The name-value parameters are separated by an ‘=’ sign.
RealmGBean |  |  |  |
GBean wrapper for Tomcat Realm objects. May only have one Realm at the Engine and Host levels (or Context within the geronimo-web.xml or equivalent plan file). |  |  |  |
 | A | className | Yes | A String representation of the underlying Tomcat Realm object. The class name should reference an object that implements the org.apache.catalina.Realm interface.
 | A | initParams | No | Name-value-pair list for attributes specific to the object as described by the className. The name-value parameters are separated by an ‘=’ sign.
ValveGBean |  |  |  |
GBean wrapper for Tomcat Valve objects. May have multiple Valve objects by chaining them together at the Engine and Host levels (or Context within the geronimo-web.xml or equivalent plan file). Chaining Valves will store and execute them in the order of the chain. |  |  |  |
 | A | className | Yes | A string representation of the underlying Tomcat Valve object. The class name should reference an object that implements the org.apache.catalina.Valve interface.
 | A | initParams | No | Name-value-pair list for attributes specific to the object as described by the className. The name-value parameters are separated by an ‘=’ sign.
 | R | NextValve | No | Reference to the next ValveGBean in the chain. If this reference attribute is not included, then this GBean is the final Valve in the chain.
Legend Type: (A) – Attribute, (R) – Reference to GBean Req: (Yes) – parameter is required, (No) – not required

Adding and removing the GBeans, and changing references and attributes as listed in Table 11-2, you can change the configuration to do things such as add virtual hosts, set up a proper SSL certificate, and add Valves and Realms. The following sections examine some of the GBean configurations that are commonly altered when setting up Tomcat.

Connectors

The ConnectorGBean and HttpsConnectorGBean GBean objects are wrappers around the Tomcat Connector object that allow the Web container to provide and accept connections from clients. They have the first line of control in the communication protocol, and control which port and address to listen on, connection thread pool management, and many other capabilities. Geronimo comes with three connectors already preconfigured: HTTP, AJP, and HTTPS. The HTTP connector is for use with the HTTP protocol and listens on port 8080. The AJP connector is for using Geronimo with a Web server such as Microsoft IIS or the Apache HTTPS server and uses port 8090. The HTTPS connector is for SSL communications and uses port 8443. Listing 11-3 shows the three connectors as they might be declared in the config.xml file.

Listing 11-3: Example Connector Configurations
Image from book

...
<module name="geronimo/tomcat/1.1/car">
    ...
  <!-- HTTP Connector -->
  <gbean name="TomcatWebConnector">
     <attribute name="host">0.0.0.0</attribute>
     <attribute name="port">8080</attribute>
  </gbean>

  <!-- AJP Connector -->
  <gbean name="TomcatAJPConnector">
     <attribute name="host">0.0.0.0</attribute>
     <attribute name="port">8009</attribute>
  </gbean>

  <!-- HTTPS Connector -->
  <gbean name="TomcatWebSSLConnector">
     <attribute name="host">0.0.0.0</attribute>
     <attribute name="port">8443</attribute>
     <attribute name="keystoreFileName"> var/security/keystores/geronimo-default
</attribute>
     <attribute name="keystorePassword">secret</attribute>
</gbean>
...
</module>
...
Image from book

This shows the override of the already configured Tomcat GBeans. You may also add connectors manually through the config.xml as shown earlier in this chapter. The simplest way to add a connector is through the Web console, as was shown in Chapter 10. There is no limit to the number of connectors you can add. The only limitation is ensuring that each of the connectors listens on a different host address and port combination and that they are named uniquely. The ConnectorGBean is used for any kind of protocol that is not secure, such as HTTP and AJP. The HttpsConnectorGBean is used only for the HTTPS protocol. Table 11-2 provides a complete listing of all the attributes and attributes for the connector GBeans.

Secure Socket Layer (SSL) Connector

Geronimo’s Tomcat container comes with a preconfigured HttpsConnectorGBean to use with the SSL protocol. This GBean uses a test certificate located at $GERONIMO_HOME/ var/security/keystores/ geronimo-default with the password “secret.” This should only be used for development and test only. If Geronimo is to be used in a production environment, this configuration should be changed. Altering this configuration is simple, because it only requires editing the keystoreFileName and keystorePassword attributes for the TomcatWebSSLConnector GBean, as shown earlier. The keystoreFileName attribute should point to the new keystore path and file. Using a relative path to the file will be relative to $GERONIMO_HOME, and using a full path for this attribute will allow you to place your keystore file in any location.

Virtual Hosts

Virtual hosts provide the capability to have a single server answer to different Web addresses, without having to give out a new IP address to each new host. Each host will examine the request and look at the address of the URL, to see if it needs to handle that request. For example, let’s assume a configuration where a single server will support two companies: www.example.com, and localhost (all others). We want a certain Web application to respond to URLs that contain www.example.com, www.example.net, www.example.org, and all others to go to the default localhost. localhost does not need alteration and is already configured properly in Geronimo’s Tomcat CAR plan.xml file. To enable a virtual host, the first thing that must be done is to verify that a DNS entry will resolve to the name and the IP address of your server. This chapter will not cover how to set up DNS, but the important thing to remember is that the DNS must resolve to the address. The second thing that must be done is to enable a virtual host is to add a HostGBean in the config.xml file, as shown in Listing 11-4.

Listing 11-4: Geronimo’s HostGBean Example Declaration
Image from book

...
<module name="geronimo/tomcat/1.1/car">
  ...
  <gbean
      name="geronimo/tomcat/1.1/car?ServiceModule=geronimo/tomcat/1.1/car,j
2eeType=Host,name=TomcatSecondHost"
      gbeanInfo="org.apache.geronimo.tomcat.HostGBean">
    <attribute name="className">org.apache.catalina.core.StandardHost</attribute>
    <attribute name="initParams">
         name=www.example.com
         appBase=
         workDir=work</attribute>
    <attribute name="aliases">www.example.net,www.example.org</attribute>
  </gbean>
  ...
</module>
...
Image from book

When adding a new HostGBean, the GBean’s name should be unique, as is the case with the example host’s GBean named TomcatSecondHost. The name value of the initParams attribute should contain one of the network names for this host to respond to. In this example, it is www.example.com. Since this host should also respond to www.example.net and www.example.org, these are added to the aliases attribute and should be comma-delimited.

This handles only the server side of the configuration of a virtual host. To deploy an application to a specific host, you must name the virtual host in the geronimo-web.xml deployment plan for that application, using a host element declaration. If this is not declared, then the Web application will be deployed to the default host. This will be covered later in this chapter.

Valves

Valves are what are known as deep Web filters that can cover an entire server, host, or individual application. Their value comes from having the ability to intercept the Web request and response before they get to the application, and/or process the request after the application’s servlets. They can provide click-through tracking, specialized logging, security functions, and much more. There are many uses for valves, and they can be applied at the Engine, Host, and Context (the Web application) levels. The valves are stackable, in that valves that are declared at the Engine level will run in addition to those declared at the Host and Context levels. Each valve declared at its level will run for any child level underneath the parent.

Geronimo configures Valves by declaring them in a valve GBean chain. The EngineGBean and HostGBeans have references called TomcatValveChain that will refer to the first Valve GBean that is part of a chain. If there is more than one Valve, the first Valve will contain a reference called NextValve that names the next Valve. This is where the chain concept comes from. You continue to add Valves on to the end of the chain. The last Valve will not have a NextValve declaration and thus is the end of the chain. Each of the Valves is added to the chain in the declaration order, so you can be sure that certain Valves can run before others.

Listing 11-5 shows an example where a HostGBean configures a Valve chain. It has its TomcatValveChain reference the FirstValve, then uses the NextValve reference to refer to the SecondValve. The SecondValve has no NextValve reference, so it is the last Valve in the chain. In this example, any Web applications that are a part of this host will run the AccessLogValve, then the SingleSignOn Valve before the requests or responses by those applications. Each of the ValveGBean objects may also use the initParams attribute to set any specific properties for the Valve declared in the className attribute.

Listing 11-5: Example Host and Valve Chain Declaration
Image from book

...
<module name="geronimo/tomcat/1.1/car">
    ...
    <gbean name="TomcatHost">
      <attribute name="className">org.apache.catalina.core.StandardHost</attribute>
      <reference name="TomcatValveChain">
        <pattern>
          <groupId>geronimo</groupId>
          <artifactId>tomcat</artifactId>
          <version>1.1</version>
          <type>car</type>
          <name>FirstValve</name>
        </pattern>
      </reference>

    </gbean>

    <gbean
name=" geronimo/tomcat/1.1/car?ServiceModule=geronimo/tomcat/1.1/car,j2eeType=Tomcat
Valve,name=FirstValve"
         gbeanInfo="org.apache.geronimo.tomcat.ValveGBean">
      <attribute name="className">
        org.apache.catalina.valves.AccessLogValve
      </attribute>
      <attribute name="initParams">
               prefix=localhost_access_log.
               suffix=.txt
               pattern=common
       </attribute>
       <reference name="NextValve">
         <pattern>
           <groupId>geronimo</groupId>
           <artifactId>tomcat</artifactId>
           <version>1.1</version>
           <type>car</type>
           <name>SecondValve</name>
         </pattern>
</reference>
    </gbean>

    <gbean
name=" geronimo/tomcat/1.1/car?ServiceModule=geronimo/tomcat/1.1/car,j2eeType=Tomcat
Valve,name=SecondValve"
        gbeanInfo="org.apache.geronimo.tomcat.ValveGBean">
      <attribute name="className">
        org.apache.catalina.authenticator.SingleSignOn
      </attribute>
    </gbean>
    ...
</module>
...
Image from book

Tomcat Realms

Tomcat Realms are different from the security Realms as described in Chapter 15. Tomcat Realms connect the Tomcat Web container to outside security implementations. They offer the ability to apply security with respect to users and roles to your Web applications. Each of the Realm objects has some capability to use a database, memory store, or other type of ability to provide user/role authentication. Only one Realm may be declared at each of the levels and may be applied to an EngineGBean, HostGBean, or referenced in a geronimo-web.xml file for the context/Web application level. Realm declarations differ from the Valves in that child declarations override the parent’s declaration for that level. The Engine level declaration will cover security for the entire server. The Host-level declaration will cover security for all contexts/Web applications that fall under that host. Context-level declaration will only apply to that Web application. At any point in the hierarchy that new declaration occurs, that Realm will override and be the default security for all children beneath it.

Tomcat comes with a number of Realms (such as the JDBCRealm, DataSourceRealm, JNDIRealm, and MemoryRealm) that typically are used in a standalone Tomcat implementation. Although these Realms can be used in Geronimo, they are not as useful as leveraging the Geronimo container-managed security. Geronimo comes with two Realm objects that make use of container-managed security:

  • TomcatJAASRealm for Java Authentication and Authorization Service (JAAS)

  • TomcatGeronimoRealm for Java Authorization Contract for Containers (JACC).

The actual Geronimo security implementation will be discussed in detail in Chapter 15. One of the important characteristics when using either of these Geronimo Realms is how the tie between the Geronimo security service and the Realm occurs. The EngineGBean and HostGBean objects require that the initParams attribute contain a name value. This name should match the realmName attribute of a GenericSecurityRealm or the applicationConfigName attribute of the ServerConfigurationEntry (see Chapter 15 for Geronimo Realm discussion). This tie is how Tomcat’s Realms can resolve the Geronimo security Realm to attach to when attaching the security at the Engine and Host levels. This means that you should name your GenericSecurityRealm GBean’s realmName or Server ConfigurationEntry GBean’s applicationConfigName with the same name as your EngineGBean object’s logical name if you apply the Realm at the Engine level, or the network name of your HostGBean if you apply the Realm at the Host level.

Listing 11-6 shows an example RealmGBean configuring a TomcatJAASRealm that is attached to an EngineGBean. The relationships are shown in bold. Notice that the EngineGBean has a reference to the TomcatJAASRealm. But the EngineGBean also is named Geronimo in its initParams attribute’s name value. That value matches the ServerConfigurationEntry GBean’s applicationConfigName attribute. How the security works and its configuration will be covered in Chapter 15, but it is important to understand how the Tomcat Realms tie to the security depending on what level they are declared at.

Listing 11-6: Example JAAS Realm Configuration for an EngineGBean
Image from book

...
<module name="geronimo/tomcat/1.1/car">
    ...
  <!-- JAAS Geronimo Login Configuration -->
  <gbean
name="geronimo/tomcat/1.1/car?ServiceModule=geronimo/tomcat/1.1/car,j2eeType=Config
urationEntry,name=tomcat-properties"
      gbeanInfo="org.apache.geronimo.security.jaas.ServerRealmConfigurationEntry">
    <attribute name="applicationConfigName">Geronimo</attribute>
    <attribute name="realmName">geronimo-properties-realm</attribute>
    <reference name="LoginService">
      <pattern>
          <groupId>geronimo</groupId>
          <artifactId>j2ee-security</artifactId>
          <version>1.1</version>
          <type>car</type>
          <name>JaasLoginService</name>
      </pattern>
    </reference>
  </gbean>

  <!-- Engine -->
  <gbean name="TomcatEngine">
    <attribute name="initParams">
      name=Geronimo
    </attribute>
    <reference name="RealmGBean">
      <pattern>
          <groupId>geronimo</groupId>
          <artifactId>tomcat</artifactId>
          <version>1.1</version>
          <type>car</type>
          <name>TomcatJAASRealm</name>
      </pattern>
  </reference>
  </gbean>

  <!-- Tomcat Realm -->
  <gbean
name="geronimo/tomcat/1.1/car?ServiceModule=geronimo/tomcat/1.1/car,j2eeType=GBean,
name=TomcatJAASRealm"
          gbeanInfo="org.apache.geronimo.tomcat.RealmGBean">
      <attribute name="className">org.apache.geronimo.tomcat.realm.TomcatJAASRealm
      </attribute>
      <attribute name="initParams">
userClassNames=org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal
roleClassNames=org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal
      </attribute>
    </gbean>
    ...
</module>
Image from book

The Context level declaration of Tomcat Realms is handled much differently, and it occurs in the geroimo-web.xml but does not tie with a name attribute. There is a decision tree the Tomcat container uses to attach a Tomcat Realm to the Web application because it looks at a number of factors for deciding which Tomcat Realm to attach to your Web application. The key components that help decide the correct Tomcat Realm to use are the <tomcat-realm> element, which is the name of a Tomcat Realm GBean, the <security-realm-name> element that contains the actual Geronimo configuration entry Realm name, and the security block elements. These elements will be covered in the next section, but for the purpose of understanding the decision mechanism, the following factors will decide the Tomcat Realm used:

  1. If a <tomcat-realm> and <security-realm-name> elements are declared in the geronimo-web.xml plan file, it will set the Tomcat Realm to the value of the <tomcat-realm> element, and the Geronimo configuration entry Realm will be referenced by the <security-realm-name> element.

  2. If a <tomcat-realm> is declared in the geronimo-web.xml plan file, but not a <security-realm-name> element, it will set the Tomcat Realm to the value of the <tomcat-realm> element, but will look for a Geronimo configuration entry Realm that is named with the context root of the application. Hence, if the application is referenced with the URL /foobar as its servlet context path, then foobar will be the link to the GenericSecurityRealm GBean’s realmName attribute or ServerConfigurationEntry GBean’s applicationConfigName attribute.

  3. If a <security-realm-name> is declared in the geronimo-web.xml plan file along with a security block, but not a <tomcat-realm> element, a TomcatGeronimoRealm will be attached to the Web application using the <security-realm-name> element’s value to attach to a Geronimo configuration entry Realm. Since no Tomcat Realm is declared, along with the security block’s presence, Geronimo assumes that JACC will be used.

  4. If a <security-realm-name> is declared in the geronimo-web.xml plan file, without a security block and <tomcat-realm> element, a TomcatJAASRealm will be attached to the Web application using the <security-realm-name> element’s value to attach to a Geronimo configuration entry Realm. Since no Tomcat Realm is declared, and there is no security block, Geronimo assumes basic JAAS will be used.

  5. If neither a <security-realm-name> nor <tomcat-realm> elements are declared in the geronimo-web.xml plan file, it will use the Tomcat Realm that is configured for the Host or Engine. It will accept the Realm that it finds first, starting with the Host as the immediate parent. In a default Geronimo configuration, this usually means a TomcatJAASRealm will be attached to the context.

Keep in mind that the existence of a Tomcat Realm in a plan does not mean it will be used by your Web application, unless you instruct your Web application to use the Realm with the web.xml deployment descriptors. So, it is safe to say that nearly every one of your Web applications will have a Tomcat Realm attached to it in one form or another. This will be covered in more detail in Chapter 15.

Context Level Configuration - geronimo-web.xml

The Servlet 2.4 specification describes a generic configuration of a Web application that allows the Web application to be portable across containers through the use of the web.xml. This means a packaged WAR file would theoretically be able to be deployed on nearly any application server or Web container without any need to change the configuration or code. However, each application server typically has additional options that can enhance the power of the application through the use of a proprietary configuration file. In standalone Tomcat, proprietary configuration is found in the context.xml file. The context.xml is a container-specific descriptor that allows additional configuration for your Web application that is particular only to standalone Tomcat. The context.xml file allows configuration such as the context path, as well as the ability to configure Valves and Realms, and other objects at the context level. Geronimo does not use this file but instead has its own equivalent proprietary configuration file; the geronimo-web.xml file. This file was covered in detail in Chapter 10, but this section will concentrate on the areas that affect Tomcat.

Many of the settings found in a server.xml and context.xml file are not appropriate for use in an application server. Geronimo handles many issues (such as deployment, application locations) and many other aspects that are set outside of Tomcat. It is for this reason that you may find certain Tomcat attributes or settings nonexistent or ignored in the Geronimo configuration.

Web Deployment Descriptor Namespace Review

Chapter 10 covered the fact that Geronimo allows for three types of geronimo-web.xml files that are controlled by the namespace declaration in the top of the plan file; generic, Jetty, and Tomcat. To review, the generic namespace may contain container-specific elements with a <container-config> and a reference to a container-specific namespace, as shown by the following:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"
 xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
 xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
 xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"
 >
   <sys:environment>
        <sys:moduleId>wrox/exampleapp/1.0/car</sys:moduleId>
        <sys:dependencies>
          <sys:dependency>
               <sys:moduleId>geronimo/j2ee-server/1.1/car</sys:moduleId>
          </sys:dependency>
        </sys:dependencies>
     </sys:environment>
...
  <!-- Container specific configuration -->
  <container-config>
    <!-- Tomcat Specific Container Declarations -->
    <tomcat xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.0/config">
      <valve-chain>FirstValve</valve-chain>
      <host>www.example.com</host>
      <cross-context/>
    </tomcat>
  </container-config>
...
</web-app>

You will typically use the generic namespace when you want your Web applications to be deployable to both the Tomcat and Jetty containers. However, most users will likely use and support a single container. The Geronimo container-specific Web deployment descriptor should be used in these situations. The difference between the generic and container specific deployment descriptors is that there is no need for a <container-config> and a <tomcat>/<jetty> element, and the container-specific elements then become a first-class citizen element of the geronimo-web.xml plan. To use a Tomcat-specific Web deployment descriptor, you would declare the following namespace in the <web-app> element:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://Geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.1"
     xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
     xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
     xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"
     >
   <sys:environment>
         <sys:moduleId>wrox/exampleapp/1.0/car</sys:moduleId>
         <sys:dependencies>
             <sys:dependency>
               <sys:moduleId>geronimo/j2ee-server/1.1/car</sys:moduleId>
             </sys:dependency>
          </sys:dependencies>
     </sys:environment>

...
    <!-– Container specific tags are first class citizen tags here -->
    <valve-chain>FirstValve</valve-chain>
    <host>www.example.com</host>
    <cross-context/>
...
</web-app>
Tomcat-Specific Web Descriptor Tags

The Tomcat standalone container’s context.xml file provides the ability to set configurations beyond the servlet specification, such as to set the context’s path, or the base URL of the application with the path attribute. It allows you to set Tomcat Realms, Valves, the Manager, clustering, and other options. To support the pluggability of these objects to your Web application, Geronimo has a set of Tomcat-only elements in the geronimo-web.xml Web descriptor plan.

Table 11-3 lists the Tomcat-specific elements that are available, as well as a description of their use.

Table 11-3: geronimo-web.xml Plan Tomcat-Specific Elements and Parameters Open table as spreadsheet
Tomcat-Specific Elements | Description
host | Which virtual host to apply to this context. This value must match one of the HostGBean object’s initParams attribute name value.
cross-context | If this element exists, it allows your Web application’s servlet context to be accessible by other Web applications. This is used heavily with portlet applications because of heavy interactions between portlets.
disable-cookies | If this element exists, it will disable cookies from being used for the Web application.
valve-chain | Reference to the first ValveGBean in a valve chain. Valves will be added to any other parent valves for this context only.
tomcat-realm | Reference to the name of a RealmGBean. Applies the Realm at this context only. Should only be used when using a custom Tomcat Realm, because Geronimo will choose the proper Realm to use based upon the configuration.
manager | Reference to the name of a ManagerGBean or GBean that extends the ManagerGBean object, Allows you to swap out the session manager for Tomcat.
cluster | Reference to the name of a CatalinaClusterGBean to enable clustering for Tomcat. Clustering GBeans are beyond the scope of this chapter.

Table 11-3 lists the elements in the order that they should appear when used in your Geronimo Web descriptor plan file. For a Tomcat container Web descriptor, these elements will come after the Web descriptor’s <context-root> and before the naming element block. These are based on a sequence for the Web descriptors for Geronimo. The entire XSDs for the geronimo-tomcat-1.1.xsd (Tomcat) and geronimo-tomcat-config-1.0.xsd (for using Tomcat-specific elements in a generic Web descriptor) are found in the Geronimo /schema directory.

One area to make note of is the <valve-chain>, <tomcat-realm>, <manager>, and <cluster> elements. These elements refer to a GBean that you can declare in the Web descriptor. Therefore, you can declare GBeans that are used only at the Web context level, since the GBeans can be declared directly in the geronimo-web.xml file.

Listing 11-7 shows an example geronimo-web.xml file that contains settings for a Web application called foobar. The namespace uses the Tomcat version to tell the deployer it will be deploying a Web application that contains a Tomcat-specific configuration. The <context-root> specifies the /foobar URL that will become the context of this application.

Listing 11-7: Example geronimo-web.xml with Tomcat-Specific Attributes and GBeans
Image from book

<?xml version="1.0" encoding="UTF-8"?>
<web-app
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/web/tomcat-1.1"
    xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
        xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
        xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"
     >
   <sys:environment>
         <sys:moduleId>wrox/exampleapp/1.0/car</sys:moduleId>
         <sys:dependencies>
             <sys:dependency>
               <sys:moduleId>geronimo/j2ee-server/1.1/car</sys:moduleId>
             </sys:dependency>
          </sys:dependencies>
     </sys:environment>

  <!-- Web Parameters -->
  <context-root>/foobar</context-root>
  <security-realm-name>geronimo-properties-realm</security-realm-name>

  <!-- Container configuration -->
  <host>www.example.com</host>
  <valve-chain>ContextValve</valve-chain>
  <tomcat-realm>ContextJAASRealm</tomcat-realm>

  <!-- Additional GBean configuration -->
  <gbean name="ContextJAASRealm"
         class="org.apache.geronimo.tomcat.RealmGBean">
    <attribute
       name="className">org.apache.geronimo.tomcat.realm.TomcatGeronimoRealm
    </attribute>
    <attribute name="initParams">
userClassNames=org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal
roleClassNames=org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal
     </attribute>
  </gbean>

  <gbean name="ContextValve" class="org.apache.geronimo.tomcat.ValveGBean">
    <attribute
name="className">org.apache.catalina.authenticator.SingleSignOn</attribute>
  </gbean>

</web-app>
Image from book

The <tomcat-realm> references the ContextJAASRealm GBean and the <valve-chain> references the ContextValve as the Valve chain for this context. The <host> references www.example.com, which is the name of a parent HostGBean that would be declared in the config.xml file. So, just like standalone Tomcat’s context.xml, you can set Tomcat objects at the Web application or context level.


Summary

Tomcat is the most popular servlet engine in the Java community, and it is included with Geronimo in either the binary format or may be enabled via the source code. Geronimo comes with a standard Tomcat configuration that works well in a development environment but will likely need configuration changes to fit the needs of a production system. This chapter covered the Tomcat configuration in Geronimo and how to change this configuration to use the Tomcat architecture as it relates to:

  • Changing configurations with the config.xml file

  • Correlation between the Tomcat server.xml/context.xml and Geronimo’s Tomcat configuration plan.xml/config.xml and geronimo-web.xml

  • Configuring the Engine, Hosts, Contexts, Realms, and Valve Tomcat objects

  • Understanding Connectors and the Geronimo Connector GBeans

  • Tomcat-specific elements in the geronimo-web.xml plan

Understanding how Tomcat can be configured and used in Geronimo can help bridge the many Tomcat-based applications to run within the Geronimo application server, leveraging the best of both worlds.

Chapter 12 discusses in detail the deployment of Enterprise JavaBeans (EJBs) in Geronimo.


Chapter 12: Deploying Enterprise Applications (EAR) with OpenEJB

Overview

Enterprise JavaBeans (EJBs) are J2EE business-tier components that encapsulate business rules in an enterprise application. There are two general types of EJBs: entity beans and session beans. Entity beans are typically backed by data from the J2EE EIS tier - usually a relational database. Modification of entity bean properties typically results in changing of RDBMS data. Entity beans are stateful (which means they maintain their states between access). Session beans are typically used to encapsulate operations, including operations on entity beans. Session beans are typically stateless (although some are stateful).

Both entity beans and session beans can be deployed to the Geronimo server. They can be deployed as part of an enterprise application, in an EAR file. They can also be deployed independently in their own EJB JAR file, enabling access from multiple enterprise applications.

The EJB container in Geronimo is OpenEJB. Release 1.x of Geronimo is OpenEJB 2. OpenEJB 2 fully supports J2EE 1.4 and EJB 2.1 specifications.

This support includes the following:

  • Container Managed Persistence 2 (CMP 2)

  • EJB query language (EJB/QL)

  • Message Driven Beans (MDBs)

  • Accessing EJB as a Web service

This chapter covers the deployment of EJBs in Geronimo in detail. Specifically, the coverage includes the following:

  • The ejb-jar.xml deployment descriptor

  • The openejb-jar.xml Geronimo-specific deployment plan

  • Referencing EJBs from Web-tier resources - from the web.xml file

  • The application.xml file and configuration for EJBs

An actual enterprise application example illustrates the descriptors and plans used in the deployment of EJBs.

By the end of this chapter, you should be familiar with creating deployment plans for a variety of EJB deployment scenarios.


The J2EE Model for EJB Access

All EJBs are managed by the Geronimo container, and execute under the auspices of OpenEJB 2 - the business-tier container within Geronimo. Access to EJB can be from a source either internal or external to the Geronimo server.

Internal access includes the following:

  • Access from Web-tier components

  • Access from other EJB components

  • Access from the client application container

External access includes the following:

  • Access from non-J2EE client

  • Access via CORBA to EJB interoperations

  • Access via Web service to EJB support

The configurations required to support these access methods are different. The focus in this chapter is on the deployment of modules for internal access. Chapter 15 explains how to configure and deploy modules for Web services and CORBA access. Access from non-J2EE client via means other than CORBA and Web services requires specialized coding and is highly application-specific; it is out of the scope of this book.

Since EJBs are typically passive code modules, they do not perform any tasks until one of their methods is invoked. To access an EJB, you must first obtain a reference to it. Components that utilize EJBs typically perform the lookup (for EJBs) using JNDI APIs. The JNDI API is an essential J2EE 1.4 API that allows the dynamic lookup of EJB at run time. In addition, the use of JNDI enables the same EJB consumer components to be deployed on any application server that supports JNDI lookup of EJBs.

J2EE applications are componentized, and each component can typically be deployed separately. This enables code reuse and maximum configuration flexibility. Depending on requirements, different EJB components can be wired up for a consumer.

Geronimo manages all the EJBs that run within it. It provides the JNDI interface to EJB consumer components. As an administrator and deployer, you will have control over the exact wiring of EJB components for an application. By associating references to specific EJB components with specific JNDI names, you can customize your deployment and application assembly according to particular business needs. Because of this, it is important to understand how to reference EJBs in Geronimo and to become familiar with where EJB references may be used within the deployment plans.

Web-Tier EJB and Resource References

In formal multi-tiered server design, the Web-tier presentation logic makes frequent use of the EJBs located in the business tier to perform business logic operations. This requires the lookup of business-tier EJBs, from Web-tier modules. Since Web-tier modules must be deployable as independent entities (as specified in the J2EE specifications), the Web-tier component code does not refer to the EJBs that it needs directly. Instead, it dynamically makes JNDI calls at run time to look up the EJBs that it needs. This lookup is via a JNDI reference name. Every Web-tier module must declare these reference names in a deployment descriptor. In this way, external references are explicitly specified by J2EE Web-tier components.

It is the job of the application deployer to wire up these reference names to actual EJB references during configuration and deployment. The syntax for actual EJB references can be different between application servers. Because of this, the mapping between JNDI reference name and EJB references is often performed in a container-specific deployment plan. In the case of Web-tier components in Geronimo, this container-specific deployment plan is the geronimo-web.xml. In the geronimo-web.xml plan of a deployed application, you will find detailed mapping between JNDI reference name and references to Geronimo-managed EJBs. EJBs are considered external references with respect to the deployed WAR component.

Figure 12-1 shows the J2EE packaging for Web-tier application, with a particular focus on external references to EJBs and other resources. Chapters 10 and 11 discuss the actual deployment of these applications. External references of a Web-tier module are not limited to EJBs alone. In Figure 12-1, notice that the WAR file is completely self-contained unit. In addition to external EJB references, the servlets and JSPs may have references to one or more of the following:

  • External adapters (such as JDBC connectors or JMS connection factories)

  • External resources

  • External environment variables

Image from book
Figure 12-1: Web-tier module references to business-tier EJBs and other resources

At the time the developer actually writes and creates the code of the servlets and JSPs in the WAR file, it is usually not possible to know what these external references will refer to. This situation is analogous to the EJB lookup one. To make deployment as flexible as possible, all of these external references are coded as a JNDI lookup against intermediate JNDI reference names. As with EJB lookup reference names, these resource reference names are tallied and specified within the deployment descriptor. For a WAR file, this deployment descriptor is the web.xml file under the WEB-INF directory of the archive.

External References in EJB JAR Files

References to external EJBs and resources are not exclusive to Web-tier modules. In fact, EJBs themselves can have dependencies on other EJBs or resources. Figure 12-2 illustrates the familiar situation.

Image from book
Figure 12-2: Business-tier references to separately deployed EJBs and other resources

Figure 12-2 reveals that EJBs in one EJB JAR file can refer to other separately deployed EJBs. In the same manner as Web-tier external references, EJBs look up one another via JNDI names. These JNDI names are declared in their J2EE deployment descriptor - ejb.xml. This deployment descriptor can be found under the META-INF subdirectory of a typical EJB JAR archive file. To wire up these references to actual EJBs managed by Geronimo, the JNDI names must be mapped to EJB references. The EJB reference syntax is unique to Geronimo, and these mappings are defined in the open-ejb.xml deployment plan. This plan can be either embedded within the EJB JAR file (under the META-INF subdirectory) or specified externally when the EJBs are deployed.

Resolving Local References within an EAR Module

An EAR module combines multiple WAR and EJB JAR modules into an enterprise application. When an EAR is created, references to EJBs in the EJB JAR modules can often be resolved without additional deployment plans. This may include references from Web-tier components in the WAR files to business-tier EJBs, or it may be references between EJBs. All of these references exist as JNDI names in deployment descriptors. When a referenced EJB is local within the same EAR module, however, the wiring can be optimized. Geronimo allows you to map JNDI names to local references in this case. Local references can often provide high-performance access to components, since direct access to the referenced objects is possible. Both the consumer and the component referenced are usually within the same JVM.

Figure 12-3 illustrates this situation.

Image from book
Figure 12-3: Resolved EJB references within an EAR module

In Figure 12-3, some references to EJBs can be resolved internally, while others are external and must be explicitly mapped in the Geronimo-specific deployment plan. For those that can be internally mapped, Geronimo tries to be very intelligent in locating the referenced EJB. Namely, Geronimo will do the following:

  • Look for EJBs within its management that support the referenced LocalHome interface

  • Look for EJBs within its management that support the referenced EJBHome interface

This strategy simplifies the configuration of internally referenced EJBs in most situations.

If there are multiple or no EJBs supporting the required interfaces, Geronimo will not be able to resolve the internal reference automatically, and the reference must be explicitly mapped in the deployment plan. When using externally referenced EJBs, the deployer/administrator must map them explicitly.

Mapping External References

The task of deploying J2EE modules to Geronimo frequently requires careful mapping of external references. External reference mappings are required when Web-tier components or business-tier EJBs refer to EJB references that cannot be resolved internally within an EAR. In these cases, additional Geronimo-specific deployment plans must be crafted to map the references specified in the J2EE deployment descriptor to actual external EJBs. Figure 12-4 illustrates this mapping exercise.

Image from book
Figure 12-4: Mapping external EJB references via a Geronimo-specific deployment plan

In Figure 12-4, it is evident that one major purpose for a Geronimo-specific deployment plan is to map declared references in a J2EE deployment descriptor to actual components within a Geronimo deployment. This mapping is not limited to externally deployed EJBs, but also applies to other container-managed objects (such as JMS admin objects, security roles, and JCA resource adapters).

Table 12-1 shows the J2EE descriptors (where the external references are declared) and their associated Geronimo-specific deployment plan (where the references are mapped to container-managed objects).

Table 12-1: J2EE Descriptors and Associated Geronimo Deployment Plan Open table as spreadsheet
J2EE Deployment Descriptor | Geronimo-Specific Deployment Plan
web.xml | geronimmo-web.xml
ejb-jar.xml | openejb-jar.xml
application.xml | geronimo-application.xml
ra.xml | geronimo-ra.xml

Uses for most of these deployment descriptors and deployment plans will be shown in the following example.


Example of Deploying Session and Entity EJBs

This example from Chapter 2 (displaying this book’s authors) has been revised for use in this chapter. To summarize the changes, the new example uses the following:

  • A session bean to query and fetch the authors information for the JSP to display

  • A CMP entity bean to represent data stored in a relational database

The relational database you will use is the Derby embedded database included as part of the Geronimo distribution. You can use another relational database if you like, with little impact on the example code. A later section shows how to create a system database pool with any RDBMS supporting JDBC.

Table 12-2 shows the software components in this example.

Table 12-2: Software Components in the Deployment Example Open table as spreadsheet
Component | Description
authors.jsp | The Presentation layer Web component that generates the Web page to display the list of authors. The data to display is obtained from the session EJB indirectly, via AppController (described next).
AppController | A Java class that acts as controller (as in the Model-View-Controller design pattern). It fetches data from the model (session bean) and attaches the data as an attribute, then the request with attribute is passed to authors.jsp for display.
AuthorsBean | A session EJB that the AppController accesses to obtain the authors information. Internally, it uses the AuthorEntityCMPBean to obtain author information from the RDBMS.
AuthorEntityCMPBean | An entity EJB that uses CMP2 supported by Geronimo to access RDBMS information.

Deploying Session and CMP Entity Beans

The following listing shows the J2EE ejb-jar.xml deployment descriptor for the session EJB:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans
2.0//EN'
'http://java.sun.com/dtd/ejb-jar_2_0.dtd'>
<ejb-jar>
  <enterprise-beans>
      <session>
          <display-name>Authors Stateless Session Bean Local Interfaces</display-
name>
          <ejb-name>AuthorsCMPEJB</ejb-name>
          <local-home>com.wrox.progeronimo.AuthorsHomeLocal</local-home>
          <local>com.wrox.progeronimo.AuthorsLocal</local>
          <ejb-class>com.wrox.progeronimo.AuthorsBean</ejb-class>
          <session-type>Stateless</session-type>
          <transaction-type>Container</transaction-type>
      <ejb-ref>
        <ejb-ref-name>AuthorBean</ejb-ref-name>
         <ejb-ref-type>Entity</ejb-ref-type>
          <home>com.wrox.progeronimo.AuthorHome</home>
          <remote>com.wrox.progeronimo.AuthorRemote</remote>
       </ejb-ref>
      </session>
  </enterprise-beans>
</ejb-jar>

This deployment descriptor is similar to ejb-jar.xml from Chapter 2, with an additional <ejb-ref> element referencing the CMP2 entity bean that is used to access the Derby database. The session bean is bundled in its own authors-ejbs.jar archive. Identically to the example from Chapter 2, the Web-tier servlet will be accessing this session bean via its local interface.

The CMP2 entity bean is packaged in an independent EJB JAR file called authors-cmpejbs.jar and contains the following ejb-jar.xml deployment descriptor:

<?xml version="1.0" encoding="US-ASCII"?>

<ejb-jar 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/ejb-jar_2_1.xsd"
    version="2.1">

    <description>
        Wrox Professional Geronimo CMP Entity Bean Example.
    </description>

    <enterprise-beans>
        <entity>
            <description>
                Name of authors
            </description>
            <ejb-name>AuthorBean</ejb-name>
            <home>com.wrox.progeronimo.AuthorHome</home>
            <remote>com.wrox.progeronimo.AuthorRemote</remote>
            <ejb-class>com.wrox.progeronimo.AuthorEntityCMPBean</ejb-class>
            <persistence-type>Container</persistence-type>
            <prim-key-class>java.lang.String</prim-key-class>
            <reentrant>false</reentrant>
            <cmp-version>2.x</cmp-version>
            <abstract-schema-name>AuthorBeanCMP2</abstract-schema-name>
            <cmp-field><field-name>id</field-name></cmp-field>
            <cmp-field><field-name>firstName</field-name></cmp-field>
            <cmp-field><field-name>lastName</field-name></cmp-field>
            <primkey-field>id</primkey-field>
            <resource-ref>
                <description>
                    This is a reference to a JDBC database.
                </description>
                <res-ref-name>jdbc/basic/entityDatabase</res-ref-name>
                <res-type>javax.sql.DataSource</res-type>
                <res-auth>Container</res-auth>
            </resource-ref>
            <query>
                <query-method>
                    <method-name>findByName</method-name>
                    <method-params>
                        <method-param>java.lang.String</method-param>
                    </method-params>
                </query-method>
                <ejb-ql>
                    <![CDATA[SELECT OBJECT(a) FROM AuthorBeanCMP2 AS a WHERE
a.firstName = ?1]]>
                </ejb-ql>
            </query>
            <query>
                <query-method>
                    <method-name>findEmptyCollection</method-name>
                    <method-params/>
                </query-method>
                <ejb-ql>
                    <![CDATA[SELECT OBJECT(a) FROM AuthorBeanCMP2 AS a WHERE 1 =
0]]>
                </ejb-ql>
            </query>
            <query>
                <query-method>
                    <method-name>findAll</method-name>
                    <method-params/>
                </query-method>
                <ejb-ql>
                    <![CDATA[SELECT OBJECT(a) FROM AuthorBeanCMP2 AS a]]>
                </ejb-ql>
            </query>

        </entity>

    </enterprise-beans>
</ejb-jar>

</ejb-jar>

In this ejb-jar.xml deployment descriptor, the mapping from the CMP EJB’s members and the fields in a database are described in detail. A reference to an external database connections pool is specified - jdbc/basic/entityDatabase. EJB query methods and their associated EJB/QL query statements are also specified here. (A discussion of the powerful J2EE CMP2 capabilities is beyond the scope of this book.)

The following section explores more details on the ejb-jar.xml file and its most frequently used component elements.

The ejb-jar.xml Deployment Descriptor

EJBs consist of Java class files that are coded to the EJB 2.0 or EJB 2.1 specification. They are bundled into JAR files for deployment. Each EJB JAR file is obliged to contain a J2EE deployment descriptor. This deployment descriptor must be named ejb-jar.xml. The general format of this descriptor is:

<ejb-jar>
  <description>
   ....
  </description>
 <enterprise-beans>
        <session>
          ... session bean description and references...
       </session>
         .....
      <entity>
          ... entity bean description and references...
      </entity>
      .....
      <message-driven>
          ... message driven bean description and references...
      </message-driven>
      ...
   </enterprise-beans>
   <relationships>
       ... description relationship between EJBs ...
    </relationships>
    <assembly-description>
        ... for assembly tool use...
   </assembly-description>
   <ejb-client-jar>
            ... path to EJB client JAR ...
    </ejb-client-jar>
</ejb-jar>

The root element is <ejb-jar>. It can contain a description of the file (including a display name), as well as a small and large icon to represent the EJB archive.

Every EJB contained in the JAR must then be described within the <enterprise-beans> subelement. More details on the content of this element are discussed in the next section. After the <enterprise- beans> description, there is a description of relationship (managed by the container). The last two optional supplements are an assembly descriptor and the name of an EJB client JAR.

Describing EJBs

To describe the EJBs contained in an EJB JAR, the <enterprise-beans> element is used within ejb-jar.xml.

The <enterprise-beans> element can contain the subelements shown in Table 12-3.

Table 12-3: The <enterprise-beans> Element in ejb-jar.xml Open table as spreadsheet
Subelement | Description
<session> | The content describes a session bean.
<entity> | The content describes an entity bean. CMP entity beans may have extensive description within this element.
<message-driven> | The content describes an MDB. MDBs are fundamentally different than session and entity beans as far as configuration. One major difference is that they can implement any interface and are not restricted to EJBHome interface.
Common Elements in Both Session and Entity EJBs

These subelements are part of both the description of a session bean (the <session> tag) and an entity bean (the <entity> element). Table 12-4 shows common elements for session beans and EJBs.

Table 12-4: Common Elements for Session Beans and EJB Open table as spreadsheet
Subelement | Description
<ejb-name> | The name of the EJB, used by the container to locate the EJB.
<home> | The fully qualified Java name for the remote home interface to the EJB, if the EJB supports a remote home interface. This element and the next must exist together.
<remote> | The fully qualified Java name for the remote interface to the EJB, if the EJB supports a remote interface. This element and the previous must exist together.
<local-home> | The fully qualified Java name for the local home interface to the EJB, if the EJB supports local home interface. This element and the next must exist together.
<local> | The fully qualified Java name for the local interface to the EJB, if the EJB supports a local interface. This element and the previous one must exist together.
<service-endpoint> | The fully qualified Java name for the service endpoint interface of the EJB, if the EJB supports Web service access. Only stateless session beans can be exposed as Web services.
<ejb-class> | The fully qualified Java class name for the implementation of the EJB.

Session Bean

In addition to the common subelements described in Table 12-4, the <session> bean element also contains the additional subelements shown in Table 12-5.

Table 12-5: Session Bean Elements Open table as spreadsheet
Subelement | Description
<session-type> | Specifies the session bean’s state management type - either Stateful or Stateless.
<transaction-type> | Specifies who is responsible for transaction management, can be either Bean or Container.
<security-role-ref> | Contains a reference used in the code to refer to a security role. Subelements can optionally provide a description and a link to a security role. See Chapter 16 for Geronimo security coverage.
<security-identity> | Has either a <use-caller-identity> or <run-as> subelement. Specifies if the EJB’s method should be called using the caller’s identity or a specific run-as identity associated with a security role. See Chapter 16 for Geronimo security coverage.
Entity Bean

In addition to the common subelements described in Table 12-5, the <entity> bean element also contains the additional subelements shown in Table 12-6.

Table 12-6: Entity Bean Elements Open table as spreadsheet
Subelement | Description
<persistence-type> | The entity EJB’s persistence management type, can be either bean (for Bean Managed Persistence - BMP) or container (for CMP).
<prim-key-class> | Fully qualified name of the Java class representing the type of the primary key field of the entity EJB. See <primkey-field> below.
<reentrant> | Can be true or false, indicating if the entity bean supports re-entrant access.
<cmp-version> | The version of CMP support required by the EJB (can be 1.x or 2.x).
<abstract-schema-name> | For CMP 2.x, specifies the abstract schema type of the EJB (used primarily for EJB/QL).
<cmp-field> | Specifies a container-managed field on the EJB.
<primkey-field> | Specifies the primary key field on the EJB. The field must already be specified as an <cmp-field> and must have Java type of <prim-key-class>.
<security-role-ref> | Contains a reference used in the code to refer to a security role. Subelements can optionally provide a description and a link to a security role. See Chapter 15 for Geronimo security coverage.
<security-identity> | Has either a <use-caller-identity> or <run-as> subelement. Specifies if the EJB’s method should be called using the caller’s identity or a specific run-as identity associated with a security role. See Chapter 15 for Geronimo security coverage.

Message Driven Beans (MDBs)

The structure and operations of an MDB are significantly different from those of session and entity beans. Because of this, the descriptor for an MDB is also different. Table 12-7 shows the subelements of the <message-driven> element for describing an MDB in an EJB JAR file.

Table 12-7: Message Driven Bean (MDB) Elements Open table as spreadsheet
Subelement | Description
<ejb-name> | The name of the EJB.
<ejb-class> | The Java class that implements the MDB.
<messaging-type> | Fully qualified Java interface name of the listener interface implemented by the MDB. If not specified, it defaults to javax.jms.MessageListener.
<transaction-type> | Specifies who is responsible for transaction management (can be either Bean or Container).
<message-destination-type> | The type of message destination that is associated with the MDB (can be queue or topic).
<message-destination-link> | Refers to a <message-destination-name> defined elsewhere in the same deployed module.
<activation-config> | Name-value property pairs for the configuration of the environment in which the MDB will be invoked.
<security-identity> | Has either a <use-caller-identity> or <run-as> subelement. Specifies if the MDB should be invoked using the caller’s identity or a specific run-as identity associated with a security role. See Chapter 15 for Geronimo security coverage.

Other Elements in ejb-jar.xml

One other subelement in ejb-jar.xml that may be worth taking a look at is the <assembly-description> subelement. This element describes the assembly of the application module. Typically, this element is edited using an assembly tool. Table 12-8 examines the pertinent subelements.

Table 12-8: <assembly-description> Subelements Open table as spreadsheet
Subelement | Description
security-role | Definition of security role for this module.
method-permission | Specifies the security role that is allowed to invoke each protected method. The role referenced must have a <security-role> defined.
container-transaction | Specifies how transaction should be handled for method invocation. A <trans-attribute> subelement can contain NotSupported, Supports, Required, RequiredNew, Mandatory, or Never. See Table 12-11.
message-destination | Defines message destinations and associated <message-definition- name> that are used within the module (for example, referenced by the MDB).
exclude-list | A list of methods that should be excluded from invocation.

The openejb-jar.xml Deployment Plan

The openejb-jar.xml is the Geronimo-specific deployment plan used to mapped referenced resources and EJBs in the deployment descriptor. For our example, the following is the openejb-jar.xml:

<?xml version="1.0"?>
<openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1">
<dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <dep:moduleId>
      <dep:groupId>wrox</dep:groupId>
      <dep:artifactId>ejbcmp2</dep:artifactId>
      <dep:version>1.1</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
    <dep:dependencies>
      <dep:dependency>
        <dep:groupId>console.dbpool</dep:groupId>
        <dep:artifactId>AuthorConnectionsPool</dep:artifactId>
        <dep:version>1.0</dep:version>
        <dep:type>rar</dep:type>
      </dep:dependency>
    </dep:dependencies>
    </dep:environment>  <cmp-connection-factory>
          <resource-link>AuthorConnectionsPool</resource-link>
     </cmp-connection-factory>    <enterprise-beans>
          <entity>
              <ejb-name>AuthorBean</ejb-name>
              <jndi-name>WroxAuthorBean</jndi-name>
              <table-name>authors</table-name>
              <cmp-field-mapping>
                  <cmp-field-name>id</cmp-field-name>
                  <table-column>authornum</table-column>
              </cmp-field-mapping>
              <cmp-field-mapping>
                  <cmp-field-name>firstName</cmp-field-name>
                  <table-column>fname</table-column>
              </cmp-field-mapping>
              <cmp-field-mapping>
                  <cmp-field-name>lastName</cmp-field-name>
                  <table-column>lname</table-column>
              </cmp-field-mapping>

              <resource-ref>
                  <ref-name>jdbc/basic/entityDatabase</ref-name>
                  <resource-link>AuthorConnectionsPool</resource-link>
              </resource-ref>
          </entity>
          </enterprise-beans>
      </openejb-jar>

This deployment plan maps the database connections pool that the CMP EJB references to a concrete database pool (created later in this chapter) managed by Geronimo. Notice in the previous bolded code how the dependency on the Derby database connection pool is configured in the environment. This allows the Geronimo deployer to find the JCA connector classes and the driver classes.

Table 12-9 provides details on some of the frequently used elements in the openjb-jar.xml deployment plan.

Table 12-9: The openejb-jar.xml Deployment Plan Open table as spreadsheet
Subelement | Description
import | You can have multiple import subelements. Each one specifies a Geronimo-managed configuration that should be made a parent of this current configuration.
dependency | Specifies JAR library files that this configuration is dependent on. You can have multiple dependency elements. Geronimo will look in the repository for JAR files that are specified here.
hidden-classes | Specifies classes that you want to hide for this configuration. Typically, all of the classes from parent class loaders are made available. Specifying this allows selective masking of classes from the parent.
non-overridable-classes | Specifies classes that you want to always load from a parent’s class loader, even if they exists on the local class loader.
cmp-connection-factory | Geronimo-managed CMP beans will use this factory to obtain connections to the RDBMS.
ejb-ql-connection-factory | The factory class used to create instances of the EJB-QL compiler class. This class compiles/ translates EJB-QL queries to SQL syntax. The default value is org.tranql.sql.EJBQLCompilerFactory, and it works with Derby, MySQL, and DB2, among others.
db-syntax-factory | The factory class for creating objects that implements the org.tranql.sql.DBSyntaxFacotry interface. This class is used in the transformation of CMP SQL. The default will work with all of the RDBMSs supported by Geronimo.
enforce-foreign-key-constraints | Default is false. Determines if SQL statements that modify the RDBMS will be carried out in a specific sequence to ensure that the state of foreign key constraints are consistent. Enabling this may affect data insert/update/delete performance but may be necessary for certain RDBMSs.
enterprise-beans | Specifies the resources referenced by <session> and <entity> EJBs. Used mainly for J2EE 1.3 compatibility and reference resources (such as JMS destinations) that are not available with 1.3 descriptors.
relationships | The list of container-managed relationships between EJBs.
message-destination | References a message-destination (such as JMS queues), which is used within the deployed WAR file.
security | Configures the security role mappings that will be used when deploying the module. Maps roles specified in the WAR file to roles or principals in the security realm. See Chapter 15 for more information on the use of this element.
gbean | Specifies additional GBeans that are configured and deployed with this module.

Resolving EJB References in Geronimo

Application tier components typically access business-tier EJBs to perform business logic. In addition, business-logic-based manipulation of entity beans is almost always handled using session beans. This means that many EJB JARs will have external references to other EJBs.

Unlike other application servers you may be familiar with (such as JBoss and Weblogic), Geronimo does not have a global JNDI space for resolving external references. Instead, you must wire up the references at deployment time using elements such as <ejb-link>. However, Geronimo assists in this wiring by providing built-in intelligence that can deduce the desired link under most circumstances without your creating explicit links. For example, local EJB references are matched by the home and local access interface type - and work reasonably well, as long as you do not have multiple EJBs satisfying the requirements in the same module.

Depending on the interface type of the EJBs, and where the EJB modules are located, the way Geronimo resolves references can be significantly different. Table 12-10 provides details on EJB reference resolution in Geronimo.

Table 12-10: EJB Reference Resolution in Geronimo Open table as spreadsheet
EJB location | EJB Interface | Reference handling
In the same EAR as the Web-tier component | Local home; local interface | The Geronimo container will attempt to match the local and home interface to the EJBs available within the same EAR to determine the EJB referenced. You can also use the <ejb-link> element to gain control to the exact mapping.
In the same EAR as the Web-tier component | Remote home; remote interface | The Geronimo container will attempt to match the local and home interface to the EJBs available within the same EAR to determine the EJB referenced. You can also use the <ejb-link> element to gain control to the exact mapping.
In another deployed module | Remote home; remote interface | An EJB reference must be specified and mapped (via <ejb-link>) for each external EJB used. Be aware that the code of the EJB must be accessible to the Web-tier module through its classloader; this may involve making the configuration that it depends on its parent.

As expected, EJBs that are located within the same JAR and use local EJB interfaces are easiest to resolve- since the container knows about them at the time of deployment. This is confirmed in Table 12-10. EJBs that are located in a separately deployed module require the most work to deploy successfully-including the task of ensuring that all the classes required by the referenced EJB can be loaded.

Mapping Internal EJB References

When you are creating a geronimo-web.xml or openejb-jar.xml file, you can map (wire up) any definitions to the actual managed EJBs. To map a reference that uses a remote interface, use the following:

<naming:ejb-ref>
    <naming:ref-name>....name.... </naming:ref-name>
    <naming:ejb-link>... link to ejb.... </naming:ejb-link>
</naming:ejb-ref>

To map a local reference, use:

<naming:ejb-local-ref>
    <naming:ref-name>.... name ......</naming:ref-name>
    <naming:ejb-link>.... link to ejb.....</naming:ejb-link>
</naming:ejb-local-ref>

This reference syntax is handy when you know that the Geronimo container can find the referenced EJB by the interface types.

Mapping External EJB References

A similar technique exists for mapping external EJB references. EJB in other modules that are addressed using remote interfaces can be mapped as follows:

<naming:ejb-ref>
    <naming:ref-name>... name of reference..... </naming:ref-name>
    <naming:domain>geronimo.server</naming:domain>
    <naming:server>geronimo</naming:server>
    <naming:application>...applicationId...</naming:application>
    <naming:module>... configId....</naming:module>
    <naming:type>... type....</naming:type>
    <naming:name>ejbname</naming:name>
</naming:ejb-ref>

Mapping EJBs with remote interfaces is similar:

<naming:ejb-ref>
    <naming:ref-name>... name of reference..... </naming:ref-name>
    <naming:domain>geronimo.server</naming:domain>
    <naming:server>geronimo</naming:server>
    <naming:application>...applicationId...</naming:application>
    <naming:module>... configId....</naming:module>
    <naming:type>... type....</naming:type>
    <naming:name>ejbname</naming:name>
</naming:ejb-ref>

General Configuration Concerns

When you are deploying EJBs, keep in mind the following:

  • All EJBs must have <ejb-ref> or <ejb-local-ref> associated with them and should have a mapping to a managed EJB in the openejb-jar.xml deployment plan.

  • You must ensure that any external classes that you need (even for dependent components) can be loaded - this typically means placing them in the repository or making the configuration that contains them your parent configuration.

  • Any role-based security declarations in deployment descriptor must be mapped to the users and/or groups of the Geronimo security realm that you plan to use (see Chapter 15).

  • Any reference to external databases (such as the database and table to back a CMP EJB) must be mapped to a running database connection pool. Database connections pools are deployed instances of JCA resource adapters for JDBC access to relational databases.

  • For any reference to JMS message destinations, the destinations must be created and deployed as admin objects on Geronimo. Any reference to JMS connection factories must be mapped to a running instance of a connection factory hosted on the Geronimo server.

Informing the Container of Components to Deploy

To inform Geronimo of components within the EAR file to deploy, you use two deployment descriptors. The first one is a standard J2EE deployment descriptor - application.xml. The following is the application.xml for this EAR file. The application.xml must be placed in the EAR file’s META-INF directory.

<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>authors-ejbs.jar</ejb>
    </module>
    <module>
        <ejb>authors-cmpejbs.jar</ejb>
    </module>
    <module>
        <web>
            <web-uri>authorscmp2.war</web-uri>
            <context-root>/progeron</context-root>
        </web>
    </module>
</application>

This application.xml file tells Geronimo that there are three modules in the EAR file to deploy, including authors-ejbs.jar (the session bean), authors-cmpejbs.jar (the entity bean), and authorscmp2.war (the Web-tier servlet and JSP).

In the application.xml, the authorscmp2.war component is also provided with a <context-root> of /progeron. This allows you to access the application later via http://localhost:8080/progeron/authors.cgi later.

In addition to the J2EE standard application.xml, a Geronimo-specific deployment plan is also included. This plan is called geronimo-application.xml. This plan contains the following:

<application
       xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1">
   <environment>
   <moduleId>
      <groupId>wrox</groupId>
      <artifactId>ejbcmp2</artifactId>
      <version>1.1</version>
      <type>car</type>
    </moduleId>
  </environment>
</application>

This geronimo-application.xml file simply provides a moduleId for the deployed module. This file can either be located in the META-INF directory of the EAR (alongside the application.xml file already there) or be specified externally during deployment, and not be a part of the EAR file at all.

The benefit of keeping it external is the fact that it can be changed externally without the need to reassemble the EAR file. The disadvantage of keeping it externally is that you must track and maintain the two files instead of one single convenient EAR bundle.

Creating Derby Databases for the CMP Entity Bean

Next, you need to create the Derby database that the AuthorBean will be linked to. This can be accomplished via the Web console.

If you select Embedded DB→DB Manager from the menu, you can add the new wroxuathors database using the RUN SQL portlet. Just enter wroxuathors in the Create DB field and click the Create button, as shown in Figure 12-5.

Image from book
Figure 12-5: Creating the wroxauthors database for the CMP bean

Once you have created the wroxauthors database, you can add an authors table into it. You can also populate it with the authors data. This can be accomplished in the same RUN SQL portlet. First, ensure that the Use DB: field has wroxauthors selected. Then, enter SQL statements into the SQL Command/s: field, and click the Run SQL button. Figure 12-6 shows the commands to create and populate the authors table.

Image from book
Figure 12-6: Creating and populating tables in the wroxauthors database

In Figure 12-6, note that the wroxauthors database is listed in the database list of the DB Viewer portlet. This is confirmation that database creation is successful.

Once you have successfully run the SQL commands in Figure 12-6, click on the Application link of the View Tables column in the DB Viewer portlet (the one next to the wroxauthor database). This link shows the application tables in the database. You will see a listing of the available tables. Select the authors table. This will display and verify the contents of the authors table you’ve just created, as shown in Figure 12-7.

Image from book
Figure 12-7: Viewing the content of the authors table in the Derby wroxauthors database

Configuring Transactions

J2EE 1.4 supports declarative transactions for EJBs managed by compatible containers. Geronimo fully supports declarative transactions (also called container-managed transactions) for all its EJBs - session beans, entity beans, or Message Driven Beans.

The main benefit of declarative transaction, managed by the container, is that it frees the software developers from having to intermix complex transaction management code in their software component. Declarative transactions defer the decision of when to set transaction boundary from development time to deployment time. They also enable the same components to be configured with different transaction boundaries, depending on the requirements of the application.

To control the transaction boundary for container-managed transactions, a Geronimo administrator can do so by setting deployment descriptor attributes. These are XML elements in the standard ejbjar.xml J2EE deployment descriptor. The attributes that controls transaction boundaries are primarily the following:

<transaction-type>

<container-transaction>

<trans-attribute>

The following discussion describes how each of these elements is used.

J2EE Transaction Attributes for EJBs

The transaction attributes (specified in the J2EE 1.4 specifications) attempt to cater to most application scenarios that exist in the real world. Table 12-11 shows these attributes.

Table 12-11: J2EE Transaction Attributes for EJBs Open table as spreadsheet
Attribute | Description
RequiresNew | If the caller is in a transaction, it is suspended while this method call is made. A new transaction is always started for this call.
Required | If the caller has a transaction, use it. Otherwise, start a new one.
Mandatory | Insists that the caller is in a transaction. If the caller is in a transaction, use it. If the caller is not in a transaction, this is an error condition and an exception will be thrown.
NotSupported | If the caller is in a transaction, that transaction is suspended while the call is made. The call is made outside of any transaction.
Supports | Go with the flow. If the caller has a transaction, that transaction is used. If the caller is not in a transaction, this call is made outside of any transaction.
Never | Insists that the caller not be in a transaction. If the caller is in a transaction, this is an error condition and an exception will be thrown. Otherwise, if the caller is not in a transaction, then make this call outside of any transaction.

Transaction attributes can either be specified at the bean level (which means that they will apply to every method exposed by an EJB) or be specified on a per-method level (providing a finer-grained control over transaction management in an application).

To apply transaction attributes on a bean level, they can be configured in a J2EE ejb-jar.xml deployment descriptor as follows:

<container-transaction>
          <method>
              <ejb-name>ProGeronEJB</ejb-name>
              <method-name>*</method-name>
          </method>
          <method>
              <ejb-name>ActiveManageEJB</ejb-name>
              <method-name>*</method-name>
          </method>
          <trans-attribute>Required</trans-attribute>
</container-transaction>

The transaction attributes can be specified at the method level, as shown here:

<container-transaction>
     <method>
         <ejb-name>ProGeronEJB</ejb-name>
         <method-name>getAuthorById</method-name>
        <method-params>
            <method-param>java.lang.Integer</method-param>
        </method-params>
    </method>
    <trans-attribute>NotSupported</trans-attribute>
</container-transaction>

Any attribute specified at the method level will override the any attribute set at the bean level.

Geronimo implements Java Transaction API 1.0 (JTA 1.0). Both container-managed transactions and bean-managed transactions (programmatic control by developers) are supported. The Geronimo transaction manager is active whenever the server is started.

Database pools can be configured to work with local transaction (local to a single database instance) or with distributed transaction via XA (working across multiple database instances). Distributed transactions across multiple resource managers (such as multiple database instances) are managed via a two-phase commit protocol.

A full discussion of the application of J2EE transactions is beyond the scope of this book.


JavaMail Support

Geronimo supports programmatic sending and receiving of email. Out of the box, Geronimo allows J2EE applications to work with email messages using the industry standard JavaMail 1.3 APIs. JavaMail is a set of APIs that enables developers to manipulate email independently of the underlying operating system and hardware platform, and independent of the actual mail transport protocols. For more information on the JavaMail API, see the following URL:

http://java.sun.com/products/javamail/index.jsp

JavaMail Transports

While the JavaMail API can work with all popular email transports such as SMTP, POP, and IMAP, the included Geronimo 1.1 implementation supports only SMTP. If your installation requires protocol support beyond SMTP, you must add third-party libraries. A more extensive module is currently under development in the Geronimo sandbox. When ready, this library will support additional protocols such as POP, and may become available as a Geronimo plug-in.

The Geronimo sandbox is where new contributions for Geronimo are incubated. These are typically system modules or sample applications. These modules are developed and tested in isolation, within the sandbox, until the Geronimo community (voted by committers) feels that the module is ready for integration into the mainstream code base.

The JavaMail API is a client-side unified API for working with differing email transport protocols. It is important to note that JavaMail support on a J2EE 1.4 server does not imply that the server may be used as a server for relaying email across the Internet. Internet mail servers are specialized servers that can work with a variety of email formats, protocols, and a very high volume of email continuously.

Handling email relay is out of the scope of the J2EE 1.4 specification, which focuses on the construction of componentized business applications. In contrast to a mail server, the JavaMail support is in J2EE 1.4, and Geronimo plays a purely client-side role.

MailSession GBean

Geronimo 1.1 provides JavaMail support through a specialized GBean. This GBean is implemented as a system module. The module is installed, but not started, by default. Following is the module ID for the JavaMail support module:

geronimo/javamail/1.1/car

The actual programming of the JavaMail API is out of the scope of this chapter. However, Geronimo administrators should know how to enable the use of this API and to configure the component to use a specific email server (by specifying the TCP address and port of the mail server).

The geronimo/javamail/1.1/car module is not started by default. You can start this module by performing one or both of the following:

  • Specifying it as a dependency in your application

  • Manually starting the module in the Web console or command-line deployer

Enabling JavaMail System Module via config.xml

To enable JavaMail support, and to configure the SMTP server that you will be using, you must edit the var/config/config.xml file. Remember to make sure that the Geronimo server is not running locally before editing this file.

The following shows the modifications that you need to make to enable JavaMail support.

...
<module load="false" name="geronimo/javamail/1.1/car">
<gbean name="SMTPTransport">
<attribute name="host">localhost</attribute>
<attribute name="port">25</attribute>
</gbean>
</module>
...

In the preceding listing, the module’s load attribute value is changed to load="true". This will cause the Geronimo server to load the geronimo/javamail/1.1/car module on the next startup. The host and port attributes for the SMTP transport are configured (overridden) via attributes of the SMTPTransport GBean.

<module
    xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1"
    >
    <gbean name="mail/MailSession" class="org.apache.geronimo.mail.MailGBean">
        <attribute name="transportProtocol">smtp</attribute>
    </gbean>
    <gbean name="SMTPTransport"
class="org.apache.geronimo.mail.SMTPTransportGBean">
        <attribute name="host">localhost</attribute>
        <attribute name="port">25</attribute>
    </gbean>
</module>

Reference to the Container-Managed JavaMail Session

Developers creating applications can reference this container-managed mail session by adding a <resource-ref> entry in their J2EE deployment descriptor. For a Web application, this can be included in the web.xml deployment descriptor, in a form similar to the following highlighted code:

<?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">
    <servlet>
      <servlet-name>myservlet</servlet-name>
      <servlet-class>MyServlet</servlet-class>
   </servlet>
   <servlet-mapping>
     <servlet-name>myservlet</servlet-name>
     <url-pattern>/mymail.cgi</url-pattern>
   </servlet-mapping>
   <resource-ref>
      <res-ref-name>wrox/mailSession</res-ref-name>
      <res-type>javax.mail.Session</res-type>
      <res-auth>Container</res-auth>
      <res-sharing-scope>Shareable</res-sharing-scope>
   </resource-ref>
</web-app>

This deployment descriptor configures a <resource-ref> with name wrox/mailSession, pointing to a container-managed javax.mail.Session object. This session can be accessed by application code by looking up via JNDI the name java:comp/env/wrox/mailSession.

Linking to the Container-Managed JavaMail Session

To link the reference name of wrox/mailSession to the JavaMail support system module’s mail/Mail Session GBean, the Geronimo administrator must create a Geronimo-specific deployment plan. For a Web application, this can be configured in a geronimo-web.xml plan similar to the following:

<?xml version="1.0" encoding="ISO-8859-1"?>
  <web-app   xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"
   >
    <environment>
    <moduleId>
        <groupId>wrox</groupId>
        <artifactId>progeronjmail</artifactId>
        <version>1.0</version>
        <type>car</type>
      </moduleId>
     <dependencies>
       <dependency>
        <groupId>geronimo</groupId>
        <artifactId>javamail</artifactId>
        <version>1.1</version>
        <type>car</type>
        </dependency>
      </dependencies>
     </environment>
      <context-root>/progeron</context-root>
      <resource-ref>
          <ref-name>wrox/mailSession</ref-name>
          <resource-link>mail/MailSession</resource-link>
      </resource-ref>
 </web-app>

The highlighted code tells Geronimo that this module is dependent on the Geronimo/javamail/ 1.1/car module. It also configures a <resource-ref>, with the name wrox/mailSession, pointing to a Geronimo-managed resource named mail/MailSession. This is the JavaMail session GBean configured in the geronimo/javamail/1.1/car module, and with properties configured in the config.xml file.


Working with the Database Connections Pool

An entity bean using CMP connects to databases via a JDBC connection pool. To prepare for database access, this pool must first be created and deployed to Geronimo.

Geronimo uses TranQL to provide database connection pooling. You must specify the following via a deployment plan:

  • The database driver to use when accessing the database

  • The database name, username, login password

  • Other connections pool configuration parameters

The deployment plan is a JCA resource adapter deployment plan, typically called geronimo-ra.xml (the name you should use if you include the plan in an EAR under the META-INF directory). You can either handcraft this plan, or use the Web Console Wizard to create one.

The following section shows how to use the Web console to create a plan for deploying a database pool.

To create the AuthorConnectionsPool, first select Services→Database Pools from the menu. Then, click the Using the Geronimo Database Wizard link to create a database pool. The first screen of this wizard is shown in Figure 12-8.

Image from book
Figure 12-8: Using the wizard to create the AuthorConnectionsPool database pool

Enter the name of the database pool as shown in Figure 12-8, and select Derby embedded as the database type. Click Next to select the driver to use and supply additional configuration information. You will be greeted with the driver selection screen, as shown in Figure 12-9.

Image from book
Figure 12-9: Setting driver and parameters for the AuthorConnectionsPool

Select the driver as shown in Figure 12-9. The displayed drivers are the ones known to this wizard, including many that already have code built into the default Geronimo repository. You can also download a driver into the repository by clicking the Download a Driver button.

In this case, you are using the embedded Derby driver already in the repository. Use APP for both the DB user and password. This user is one already configured for the Derby database.

Enter wroxauthors into the Database: field. Click Next. On the final screen, accept everything by default and click the Test Connection button. This will test the connection pool you’ve just created. After testing, you can click the Show Plan button. This will display the resource adapter deployment plan that you can use to deploy this database connection pool, as shown in Figure 12-10.

Image from book
Figure 12-10: Displaying the deployment plan for the deployment of AuthorConnectionsPool

The generated deployment plan is shown in the following listing:

<?xml version="1.0" encoding="UTF-8"?>
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1">
    <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
        <dep:moduleId>
            <dep:groupId>console.dbpool</dep:groupId>
            <dep:artifactId>AuthorConnectionsPool</dep:artifactId>
            <dep:version>1.0</dep:version>
            <dep:type>rar</dep:type>
        </dep:moduleId>
        <dep:dependencies>
            <dep:dependency>
                <dep:groupId>org.apache.derby</dep:groupId>
                <dep:artifactId>derby</dep:artifactId>
                <dep:version>10.1.1.0</dep:version>
                <dep:type>jar</dep:type>
            </dep:dependency>
        </dep:dependencies>
    </dep:environment>
    <resourceadapter>
        <outbound-resourceadapter>
            <connection-definition>
                <connectionfactory-
interface>javax.sql.DataSource</connectionfactory-interface>
                <connectiondefinition-instance>
                    <name>AuthorConnectionsPool</name>
                    <config-property-setting name="Password">APP</config-property-
setting>
                    <config-property-setting
name="Driver">org.apache.derby.jdbc.EmbeddedDriver</config-property-setting>
                    <config-property-setting name="UserName">APP</config-property-
setting>
                    <config-property-setting
name="ConnectionURL">jdbc:derby:wroxauthors</config-property-setting>
                    <connectionmanager>
                        <local-transaction/>
                        <single-pool>
                            <max-size>10</max-size>
                            <min-size>0</min-size>
                            <match-one/>
                        </single-pool>
                    </connectionmanager>
                </connectiondefinition-instance>
            </connection-definition>
        </outbound-resourceadapter>
    </resourceadapter>
</connector>

At this point, you can either save the deployment plan in a file and include it as geronimo-ra.xml under the META-INF directory in the EAR file or you can click the Deploy Pool button now. If you include the plan in the EAR, the database pool will be deployed with the application - and undeployed when you undeploy the application’s configuration.

If you click the Deploy Pool button, the database pool will be deployed immediately and ready for use by any application running on the server instance.

You will see more examples of resource adapter deployment plans (and explanations of the elements used in this plan) in Chapter 13.

After deploying the database pool, you will see it listed in the Database Pools portlet, as shown in Figure 12-11.

Image from book
Figure 12-11: Successful deployment of the AuthorConnectionsPool

Trying Out the Example

Deploy the authorscmp2.ear to Geronimo, and try out the URL:

http://localhost:8080/progeron/authors.cgi

You should see the list of authors displayed as in Chapter 2. However, this time, the data is retrieved via the session bean querying the CMP entity bean - fetching data from the Derby database. Figure 12-12 shows the list.

Image from book
Figure 12-12: The example running with data from Derby RDBMS

If you change any deployment descriptor, remember to rebuild the EAR file before redeploying the application. This can be accomplished using the following Ant command:

ant ear

The ear target in the build.xml file will take care of compiling and assembling the EAR file after your modifications.


The Geronimo Client Container

Most of the time, users of Web applications hosted in Geronimo access the application via a Web browser. At the Web-tier, Geronimo supports Tomcat or Jetty, enabling the deployment of a very rich set of user interface-rendering technologies. For compatibility with existing legacy systems and architecture, Geronimo provides a client application container. The main consumers of the client application container are custom coded fat-clients that provide their own user interfaces (either command line or GUI). The Geronimo client application container provides the fat-client code with easy access to Geronimo components, providing it with a component access environment (through JNDI) that is very similar to the server-side environment.

The operations of the Geronimo client application container are shown in Figure 12-13.

Image from book
Figure 12-13: The Geronimo application client container

In Figure 12-13, note that the main value-add of the Geronimo client application container is in ease-of-development. It is possible to create fat clients even without the client application container support. The client application container provides a J2EE programming environment on the client side by remotely accessing the corresponding server-side resources. By using the client application container, the code in the client can look up Geronimo-hosted components (such as EJBs and connectors) via direct JNDI lookup.


Summary

This chapter describes how to deploy EJB modules into Geronimo. EJB modules are bundled in JAR files with an embedded ejb-jar.xml deployment descriptor. This J2EE deployment descriptor describes all the EJBs that are in the bundle. It also describes references to external resources that the EJBs depend on. This can include other EJBs, resource adapters (such as JDBC connectors and JMS connection factories) and also container-managed resources (such as message destinations and security roles).

Simple EJB modules that are created to be deployed in a known environment can occasionally be deployed to Geronimo without additional Geronimo-specific deployment plan. In most cases, however, the creation of openejb-jar.xml is required. This Geronimo-specific deployment plan maps the references of the EJB module(s) to actual known resources in the container.

The intelligence built into the container for locating resources significantly simplifies the creation of the deployment plan. For example, external EJB references are matched by the container based on the home and remote (or local) interfaces by the container.

Geronimo also has built-in support for JavaMail, and provides backward compatibility with fat-client applications with a client application container.

Chapter 13 explores the deployment of JDBC resources in Geronimo.


Chapter 13: Configuring and Deploying JDBC Resources with PostgreSQL

Overview

Relational database management systems (RDBMSs) are a cornerstone fixture of almost all enterprise systems. To handle database connections, most modern Java application servers utilize the J2EE Connector Architecture 1.5 (JCA) to create a pool of connection objects that is managed by the application server. In addition to JDBC connections, a JCA resource adapter can also manage JMS connection factories. This will be the subject of Chapter 16.

Relational databases are everywhere, and there are many from which to choose. This chapter discusses PostgreSQL. Started as a follow-on project to the Ingres project, the POSTGRES (post-Ingres) project began in 1986 at the University of California, Berkeley and has enjoyed a long and healthy life in the Open Source community. Today, PostgreSQL is a BSD-licensed, Open Source, relational database developed by the community.

Now backed in various forms by such companies as Pervasive Software, EnterpriseDB, and Greenplum, PostgreSQL is an enterprise-ready relational database with an impressive set of features. It provides such functionality as cursors, full outer joins, functions, indexes, inheritance, multi-version concurrency, point-in-time recovery, spatial data types, transactionality (both distributed and local), triggers, user-defined types, views, and much, much more.

While this chapter does not outline all the necessary details to get PostgreSQL configured, there are many documents available that cover this topic in depth, starting with the official documentation at the PostgreSQL Web site (http://www.postgresql.org/). This chapter assumes that PostgreSQL is set up on the localhost. Replacing the term localhost with the location of your PostgreSQL instance should work just fine. The version of PostgreSQL being used for this chapter is:

bsnyder=# select version();
                                      version
-----------------------------------------------------------------------------------
 PostgreSQL 8.1.3 on i686-apple-darwin8.6.1, compiled by GCC i686-apple-darwin8-
gcc-4.0.1 (GCC) 4.0.1 (Apple Computer, Inc. build 5332)
(1 row)

bsnyder=#

Note that the preceding command can only be run once the PostgreSQL server is up and running. See the section “Starting PostgreSQL” later in this chapter for a discussion on the start command.

Notice that this version of PostgreSQL (8.1.3) was compiled for Mac OS X (see the powerpc-apple- darwin8.6.1 reference in the previous code). Note that there is no requirement to use Mac OS X for this chapter.


Architecture

PostgreSQL employs a standard client/server architecture, whereby the database server accepts connections from a client in a local or remote fashion. If the client and server are installed on the same host, a first-in, first-out (FIFO) buffer is used for communication. If the client and server are installed on different hosts, the two communicate over a TCP/IP network connection. Once a connection is made, the PostgreSQL internals take over.

Let’s take a brief look at the PostgreSQL architecture shown in Figure 13-1. This information is intentionally high-level to convey the general meaning without diving too deep. Connections coming into the server begin at the top of the diagram with Main. Main passes control to either the Postmaster or directly to the Postgres engine(s). The Postmaster controls the PostgreSQL startup and shutdown. To handle concurrency, the Postmaster forks a new process for each new connection that arrives. Postgres is the database engine and handles all calls to the various internals, including the Parser, the Optimizer, and the Executor. The Parser is a query parser that breaks a SQL query down into a tree of nodes. The Optimizer creates an optimal plan for the Executor. The Executor executes the plan of nodes for Create Read, Update, and Delete (CRUD) statements. Beneath the Executor are the Storage Managers, SQL Query Nodes, the Catalog, and Data Access modules. These items handle all the access to the data in memory and on disk.

Image from book
Figure 13-1: PostgreSQL architecture

As for security, PostgreSQL is fairly locked down in the sense that remote connections are not available by default. To allow remote connections, a special configuration is required on the server side (the pg_hba.conf file) and the server must be started up with the -i flag to allow for remote, TCP/IP connections. Now that the brief overview of the PostgreSQL architecture is complete, the next concern is getting PostgreSQL up and running.


Starting PostgreSQL

PostgreSQL is generally started from the command line using the pg_ctl utility, but usually only the postgres user can execute this utility. If you followed standard PostgreSQL installation instructions, then this will apply. Upon becoming the postgres user, the following command can be executed from the command line to start the PostgreSQL server:

[postgres]$ pg_ctl -o"-i" -D /usr/local/pgsql/data \
-l /usr/local/pgsql/pg.log start
postmaster starting

This command tells the pg_ctl utility to start the PostgreSQL server by passing the -i option to allow TCP/IP (remote) connections (the -o argument passes anything in quotation marks directly to the PostgreSQL server), using the /usr/local/pgsql/data directory to hold all data files and tell the log statements to go into the /usr/local/pgsql/pg.log file.

Notice the message in the previous output when executing pg_ctl that indicates that PostgreSQL is being started. The postmaster fronts the PostgreSQL server, and this message is simply pg_ctl telling you that the server is going to start up. To be sure that it actually did start, take a peak in the log file that was specified earlier and it will show some additional information similar to the following:

LOG:  database system was shut down at 2005-11-06 13:00:20 MST
LOG:  checkpoint record is at 0/A5F09C
LOG:  redo record is at 0/A5F09C; undo record is at 0/0; shutdown TRUE
LOG:  next transaction ID: 560; next OID: 17232
LOG:  database system is ready

The important part of the log file above is the last statement, indicating that the database is ready. Now that a PostgreSQL instance is running, the next topic of concern is how JDBC resources help Geronimo communicate with this PostgreSQL instance.


J2EE Connector Architecture and JDBC Resources

JCA provides an independent and standardized mechanism for integrating with systems external to an application server via a standard set of contracts. JCA defines contracts for the management of lifecycle, connections, transactions, security, work, message inflow, and transaction inflow. Apache Geronimo supports JCA 1.5 and utilizes it to provide JMS resources and JDBC connection pooling. Through the use of a JCA resource adapter descriptor, the JDBC resources can be packaged up in a Resource Adapter Archive (RAR) file and deployed into the Geronimo server. This section explores the contents of a RAR file.

The Resource Adapter Archive

The RAR file is packaged using the jar tool and must include a deployment descriptor in a META-INF directory, as well as any additional items such as Java classes, native libraries, and any documentation and images. These contents and their locations are broken down in Table 13-1.

Table 13-1: The RAR File Contents Open table as spreadsheet
Item | Required | Location
Deployment Descriptor | Yes | META-INF/ra.xml
Documentation | No | Arbitrary
Dependent Classes | No | Arbitrary
Native Libraries | No | Arbitrary

The deployment of these resources takes place via the resource adapter deployment descriptor and the tranql-connector-derby-embed-xa-1.1.rar file. The contents of this RAR file are shown in Listing 13-1.

Listing 13-1: The Contents of the tranql-connector-derby-embed-xa-1.1.rar File
Image from book
META-INF/
META-INF/MANIFEST.MF
META-INF/ra.xml
tranql-connector-1.1.jar
tranql-connector-derby-common-1.1.jar
Image from book

The tranql-connector-derby-embed-xa-1.1.rar file comes from the TranQL project (http:// tranql.codehaus.org/) and is a very specific resource adapter designed to support the embedded API for Apache Derby. To deploy a RAR file, it needs a deployment plan. The deployment plan and the RAR file are fed to the Geronimo deployer and deployed to the Geronimo server. This whole process will be outlined later in the chapter. For now, the process of creating a deployment plan will be covered.


Configuring JDBC Resources

JDBC resources in Geronimo are nothing more than a deployment plan for a resource adapter. In this chapter, the tranql-connector-1.2.rar file will be resource adapter that is being configured. Taking a peek at existing deployment plans that are already part of Geronimo is a good place to start because it will provide a base understanding before moving on to the PostgreSQL-specific deployment plan.

Listing 13-2 shows the system-database deployment plan. This section will focus on paring down this plan to manually create a deployment plan for PostgreSQL.

Listing 13-2: The system-database Deployment Plan
Image from book
<?xml version="1.0" encoding="UTF-8"?>
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1">
  <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <dep:moduleId>
      <dep:groupId>geronimo</dep:groupId>
      <dep:artifactId>system-database</dep:artifactId>
      <dep:version>1.1</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
    <dep:dependencies>
      <dep:dependency>
        <dep:groupId>geronimo</dep:groupId>
        <dep:artifactId>j2ee-server</dep:artifactId>
        <dep:type>car</dep:type>
      </dep:dependency>
      <dep:dependency>
        <dep:groupId>geronimo</dep:groupId>
        <dep:artifactId>geronimo-derby</dep:artifactId>
        <dep:type>jar</dep:type>
        <dep:import>classes</dep:import>
      </dep:dependency>
      <dep:dependency>
        <dep:groupId>org.apache.derby</dep:groupId>
        <dep:artifactId>derby</dep:artifactId>
        <dep:type>jar</dep:type>
        <dep:import>classes</dep:import>
      </dep:dependency>
      <dep:dependency>
        <dep:groupId>org.apache.derby</dep:groupId>
        <dep:artifactId>derbynet</dep:artifactId>
        <dep:type>jar</dep:type>
        <dep:import>classes</dep:import>
      </dep:dependency>
      <dep:dependency>
        <dep:groupId>geronimo</dep:groupId>
        <dep:artifactId>geronimo-timer</dep:artifactId>
        <dep:type>jar</dep:type>
        <dep:import>classes</dep:import>
      </dep:dependency>
    </dep:dependencies>
    <dep:hidden-classes/>
    <dep:non-overridable-classes/>
  </dep:environment>
  <resourceadapter>
    <outbound-resourceadapter>
      <connection-definition>
        <connectionfactory-interface>javax.sql.DataSource</connectionfactory-
interface>
        <connectiondefinition-instance>
          <name>SystemDatasource</name>
          <config-property-setting name="UserName"/>
          <config-property-setting name="Password"/>
          <config-property-setting name="DatabaseName">SystemDatabase</config-
property-setting>
          <config-property-setting name="CreateDatabase">true</config-property-
setting>
          <connectionmanager>
            <xa-transaction>
              <transaction-caching/>
            </xa-transaction>
            <single-pool>
              <max-size>100</max-size>
              <blocking-timeout-milliseconds>5000</blocking-timeout-milliseconds>
              <match-one/>
            </single-pool>
          </connectionmanager>
        </connectiondefinition-instance>
      </connection-definition>
    </outbound-resourceadapter>
  </resourceadapter>
  <gbean name="DerbySystem" class="org.apache.geronimo.derby.DerbySystemGBean">
    <reference name="ServerInfo">
      <name>ServerInfo</name>
    </reference>
    <attribute name="derbySystemHome">var/derby</attribute>
  </gbean>
  <gbean name="DerbyNetwork" class="org.apache.geronimo.derby.DerbyNetworkGBean">
    <reference name="derbySystem">
      <name>DerbySystem</name>
    </reference>
    <attribute name="host">localhost</attribute>
    <attribute name="port">1527</attribute>
  </gbean>
  <gbean name="DerbyLog" class="org.apache.geronimo.derby.DerbyLogGBean">
    <reference name="DerbySystem">
      <name>DerbySystem</name>
    </reference>
  </gbean>
  <gbean name="TransactionalThreadPooledTimer"
class="org.apache.geronimo.timer.jdbc.JDBCStoreThreadPooledTransactionalTimer">
    <attribute name="repeatCount">5</attribute>
    <reference name="TransactionContextManager">
      <name>TransactionContextManager</name>
    </reference>
    <reference name="ManagedConnectionFactoryWrapper">
      <name>SystemDatasource</name>
    </reference>
    <reference name="ThreadPool">
      <name>DefaultThreadPool</name>
    </reference>
    <dependency>
      <name>DerbySystem</name>
    </dependency>
  </gbean>
  <gbean name="NonTransactionalThreadPooledTimer"
class="org.apache.geronimo.timer.jdbc.JDBCStoreThreadPooledNonTransactionalTimer">
    <reference name="TransactionContextManager">
      <name>TransactionContextManager</name>
    </reference>
    <reference name="ManagedConnectionFactoryWrapper">
      <name>SystemDatasource</name>
    </reference>
    <reference name="ThreadPool">
      <name>DefaultThreadPool</name>
    </reference>
    <dependency>
      <name>DerbySystem</name>
    </dependency>
  </gbean>
</connector>
Image from book

Listing 13-2 contains the system-database deployment plan. This deployment plan uses the Apache Derby database, so some of the dependencies, the config-property-setting elements and the GBeans are very Derby-specific and do not apply to other databases. For example, PostgreSQL would not recognize the parameter list in Listing 13-2 named CreateDatabase. Also note that there is no JDBC URL included in the previous plan. This is because the plan is deployed with a JCA connector for the Derby embedded database that doesn’t require a URL because it makes use of Derby’s embedded API.

Conversely, PostgreSQL requires parameters that Derby would not understand. The only idea in starting with the system-database plan is that it provides a place to begin to understand an example that already works properly. To understand this plan fully, let’s examine the contents a bit more.

Table 13-2 contains the allowed content for a JCA connector and resource adapter for JDBC resources.

Table 13-2: Allowed Content of a Resource Adapter Plan Open table as spreadsheet
Item | Description
environment | An encapsulating root element for the module plan file.
connector | The root element of the deployment descriptor for the resource adapter. This element includes general information and also includes information specific to the implementation of the resource adapter library as specified through the element resourceadapter.
moduleId | The unique identifier for the descriptor.
dependencies | Holds all the dependency information.
hidden-classes | A list of classes that will never be loaded from parent class loaders of this module. The classes are specified in zero or more child filter elements where each filter element specifies a fully qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed here will be treated as hidden.
non-overridable-classes | A list of classes that will only be loaded from parent class loaders of this module (never from the module’s own class loader). Just as with the hidden-classes element, the classes are specified in zero or more child filter elements where each filter element specifies a fully qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed here will be treated as hidden.
resourceadapter | A container element holding the resourceadapter-instance and outbound-resourceadapter elements.
workmanager | A container element holding one of gbean-link, target-name, or a group of elements including domain, server, application, module, type, and name. The work manager handles work on behalf of the resource adapter in a parallel-processing manner.
resourceadapter-instance | A container element to hold the necessary information about the resource adapter and its configuration.
resourceadapter-name | A simple name for the resource adapter.
outbound-resource adapter | Specifies information about an outbound resource adapter, including fully qualified names of classes and interfaces required as part of the connector architecture-specified contracts for connection management, level of transaction support provided, one or more authentication mechanisms supported, and additional required security permissions.
connection-definition | A container element holding information about a connection that implements a particular interface.
connectionfactory-interface | The fully qualified package path to the implemented interface.
connection definition-instance | Additional interfaces implemented by the connection factory, used by the application.
implemented-interface | The actual interface that the implementation covers.
connectionmanager | The configuration of the connection manager.
container-managed-security | A wrapper element containing information to customize the container managed security.
no-transaction | An empty marker element indicating that the resource adapter does not participate in transactions.
local-transaction | An element indicating that the resource adapter can participate in local transactions only.
xa-transaction | An element indicating that the resource adapter can participate in distributed transactions.
transaction-caching | An element that allows resources to be shared during the duration of the transaction. This is dependent upon whether the resource has been marked as shareable.
thread-caching | An element that allows the sharing of a single connection across transactions.
transaction-log | An element that allows a local JDBC resource to be able to participate in XA transactions.
no-pool | Indicates that no connection pool should be used (that is, each request will cause a new connection to be established).
single-pool | Indicates that a single connection pool should be used.
match-one | This element indicates that the first connection acquired from the pool should be tested for validity against the pooling criteria.
match-all | This element indicates that all connection acquired from the pool should be tested for validity against the pooling criteria.
select-one-assume-match | This element indicates that no connections acquired from the pool should be tested.
partitioned-pool | Indicates that a partitioned connection pool should be used. Partitioned connection pools are segregated into many single pools, using one of the marker subelements of partition-by-subject or partition-by-connectionrequestinfo.
partition-by-subject | An element to indicate that one partition per subject should be used.
partition-by-connection requestinfo | An element indicating that one partition per set of connection request information.
max-size | The maximum number of connections in a single pool or a partitioned pool. Once this size is reached, requests will begin to block until a connection becomes available. The default is 10.
min-size | The minimum number of connections in a single pool or a partitioned pool. The default is zero.
blocking-timeout-milliseconds | This element indicates the timeout period when waiting for a connection to be returned from a pool when all connections in a pool are in use and the pool has already reached its max-size. The default is 5000 milliseconds.
idle-timeout-minutes | The amount of time a connection is allowed to go unused before it is automatically closed. The default is 15 minutes.
adminobject | Specifies information about an administered object. Administered objects are specific to a messaging style or message provider. This contains information on the Java type of the interface implemented by an administered object, its Java class name, and its configuration properties.
adminobject-interface | The interface implemented by the adminobject-class element.
adminobject-class | The implementation class of the adminobject-interface element.
adminobject-instance | A container element holding the configuration information for this adminobject element.
message-destination-name | A unique name for the adminobject to be used for the JNDI ENC.
config-property-setting | Contains an arbitrary name/value pair for configuration of the adminobject.
gbean | An element for describing GBeans within the resource adapter.

Table 13-1 covers the geronimo-connector-1.1 schema but not the connector-1.5 schema, so it’s not 100 percent exhaustive.

Table 13-2 defines the allowed contents of an instance of a resource adapter deployment plan. Now that the allowed content has been presented, the content of the instance in Listing 13-2 should be explored and Table 13-3 does just that.

Table 13-3: Contents of the TranQL Embedded Resource Adapter Configured for Derby Open table as spreadsheet
Item | Description
geronimo/system-database/1.1/car | This is the unique ID that is generated by flattening the contents of the moduleId element. This string doesn’t reside in the ra.xml but is used to uniquely identify it throughout Geronimo.
dependencies | The necessary dependencies for the TranQL Derby embedded resource adapter configuration.
javax.sql.DataSource | The fully qualified package name of the interface to be used by the connection factory.
<connection definition-instance> | This element contains as many config-property-setting elements as are necessary to define metadata for the connection (for example, username, password, JDBC URL, and so on). In addition, other elements are present for the configuration of the connection manager. In this particular case, there exists a parameter named CreateDatabase. This is specific to Derby and instructs the database engine to create the database if it does not already exist.
SystemDatasource | This is a simple string name for this connection definition instance.
<connectionmanager> | The connection manager is responsible for actually handling the JDBC connection pool. The contained elements inform the connection manager to participate in distributed transactions, to share connections among components, and to maintain a single connection pool whose maximum size is 100 connections with a blocking timeout of 5000 milliseconds to wait for any connection to become available and to test only one connection in the pool.
DerbySystem | This is a GBean that can be found already deployed to the kernel that is identified by this unique name. It is used to start an embedded instance of Derby. This is referring to the org.apache.geronimo.derby.DerbySystemGBean object.
DerbyNetwork | This is a GBean that can also be found already deployed to the kernel that is identified by this unique name. This GBean is used to manage network access to the embedded instance of Derby. This refers to the org.apache.geronimo.derby.DerbyNetworkGBean object.
Transactional ThreadPooledTimer | This is an implementation of a java.util.Timer that is persistent and transactional.
NonTransactional ThreadPooledTimer | This is an implementation of a java.util.Timer that is persistent but not transactional.

Table 13-2 documents the allowed contents of the system database deployment plan, and Table 13-3 documents an instance of that plan. This is a fairly straightforward configuration of a resource adapter for a JDBC resource. With this complete, the next task is to deploy this resource so that it’s made available for use with the Geronimo server.

Creating a JDBC Deployment Plan for PostgreSQL

Creating a deployment plan for PostgreSQL is not all that different from the Apache Derby deployment plan that was reviewed earlier in this chapter. In fact, a very basic deployment plan is actually even easier than the system database deployment plan that starts up Derby. Listing 13-3 shows a deployment plan named postgresql-plan.xml.

Listing 13-3: A deployment Plan for PostgreSQL
Image from book
<?xml version="1.0" encoding="UTF-8"?>
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1">
  <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <dep:moduleId>
      <dep:groupId>postgresql</dep:groupId>
      <dep:artifactId>postgresql</dep:artifactId>
      <dep:version>1.0</dep:version>
      <dep:type>rar</dep:type>
    </dep:moduleId>
    <dep:dependencies>
      <dep:dependency>
        <dep:groupId>postgresql</dep:groupId>
        <dep:artifactId>postgresql-8.1</dep:artifactId>
        <dep:version>404.jdbc3</dep:version>
        <dep:type>jar</dep:type>
      </dep:dependency>
    </dep:dependencies>
  <resourceadapter>
    <outbound-resourceadapter>
      <connection-definition>
        <connectionfactory-interface>
          javax.sql.DataSource
        </connectionfactory-interface>
        <connectiondefinition-instance>
          <name>PostgreSQLDataSource</name>
          <config-property-setting name="UserName">
            geronimo
          </config-property-setting>
          <config-property-setting name="Password">
            geronimo
          </config-property-setting>
          <config-property-setting name="Driver">
            org.postgresql.Driver
          </config-property-setting>
          <config-property-setting name="ConnectionURL">
            jdbc:postgresql://localhost:5432/test
          </config-property-setting>
          <connectionmanager>
            <local-transaction/>
            <single-pool>
              <max-size>10</max-size>
              <min-size>0</min-size>
              <match-one/>
            </single-pool>
          </connectionmanager>
        </connectiondefinition-instance>
      </connection-definition>
    </outbound-resourceadapter>
  </resourceadapter>
</connector>
Image from book

The only real difference that this plan has over the system-database plan outlined previously is the inclusion of a global JNDI name. Table 13-4 contains a breakdown of the deployment plan for PostgreSQL.

Table 13-4: A Deployment Plan for PostgreSQL Open table as spreadsheet
Item | Description
PostgreSQLDatabase | This is the unique ID for this deployment plan. The only requirement of this attribute is that it be a unique string.
dependencies | The necessary dependencies for the generic TranQL resource adapter.
postgresql/jars/postgresql-8.0-312.jdbc3.jar | This is a jar dependency that must be deployed to the kernel prior to this plan being deployed. The path to the PostgreSQL JDBC driver jar is relative to the Geronimo repository. (That is, the PostgreSQL JDBC drivers will need to be placed in the repository in this directory structure.)
javax.sql.DataSource | The fully qualified package name of the interface used by the connection factory.
<connection definition-instance> | This element contains as many config-property-setting elements as is necessary to define metadata for the connection (for example, username, password, JDBC URL, and so on). In addition, other elements are present for the configuration of the connection manager.
PostgreSQLDataSource | This is a simple string name for this connection definition instance.
<connectionmanager> | The connection manager is responsible for handling the JMS connections. The elements contained herein tell the connection manager to participate in distributed transactions, to share connections among components, and to maintain a single connection pool whose maximum size is 10 connections with a blocking timeout of 5000 milliseconds to wait for any connection to become available and to test only one connection in the pool.

Table 13-4 documents the contents of the deployment plan for PostgreSQL. This is a fairly straightforward configuration of a resource adapter for a JDBC resource. With this complete, the next task is to deploy this resource so that it’s made available for use with the Geronimo server.


Deploying JDBC Resources

By default, the Geronimo server installs system-database module for JDBC resources. Again, this deployment plan is specific to the Apache Derby database, but it serves as a good example.

Using the Geronimo Deployer

There is a script available in the bin directory for directly accessing the Geronimo deployer. For example, use the following command to deploy the PostgreSQL database plan:

$ ./bin/deploy.sh --user system --password manager deploy \
  /path/to/postgresql-plan.xml \
  repository/tranql/tranql-connector/1.2/tranql-connector-1.2.rar
Using GERONIMO_BASE:   /Users/bsnyder/geronimo-1.1
Using GERONIMO_HOME:   /Users/bsnyder/geronimo-1.1
Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp
Using JRE_HOME:
/System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home
    Deployed postgresql/postgresql/1.0/rar

Upon successful deployment of a plan, the preceding text is output to the command line. But there is also some information available in the var/log/geronimo.log file, as displayed in Listing 13-4.

Listing 13-4: Output from the Deployment of postgresql-plan.xml
Image from book
02:34:22,299 DEBUG [GBeanSingleReference] Waiting to start
postgresql/postgresql/1.0/rar?J2EEApplication=null,j2eeType=ResourceAdapterModule,n
ame=postgresql/postgresql/1.0/rar because no targets are running for reference
ResourceAdapter matching the patterns
postgresql/postgresql/1.0/rar?J2EEApplication=null,ResourceAdapterModule=postgresql
/postgresql/1.0/rar,j2eeType=ResourceAdapter,name=postgresql/postgresql/1.0/rar
02:34:22,330 DEBUG [GBeanSingleReference] Waiting to start
postgresql/postgresql/1.0/rar?J2EEApplication=null,ResourceAdapterModule=postgresql
/postgresql/1.0/rar,j2eeType=ResourceAdapter,name=postgresql/postgresql/1.0/rar
because no targets are running for reference JCAResource matching the patterns
postgresql/postgresql/1.0/rar?J2EEApplication=null,ResourceAdapter=postgresql/postg
resql/1.0/rar,ResourceAdapterModule=postgresql/postgresql/1.0/rar,j2eeType=JCAResou
rce,name=postgresql/postgresql/1.0/rar
Image from book

In addition to the output shown, the Geronimo console can also display the J2EE resource adapters that have been deployed. Figure 13-2 shows an example of this.

Image from book
Figure 13-2: Geronimo console display of deployed J2EE resource adapters

Notice that, in addition to the standard system-database resource adapter (whose name is geronimo/ system-database/1.1/car), and the activemq resource adapter (whose name is geronimo/ activemq/1.1/car), the PostgreSQL resource adapter deployment plan is also now currently running (whose name is postgresql/postgresql/1.0/rar). But the deployment plan for PostgreSQL is not very scalable. So, what can be done about this situation? The answer lies in the Geronimo console with regard to configuring a database connection pool.

Using the Geronimo Console

The easiest and most expedient manner in which to deploy/configure JDBC resources is through the use of the Geronimo Web console. The console contains a section under the Service heading named Database Pools that contains a wizard for creating JDBC pools. Not only will this wizard walk you through the configuration of the JDBC pool, but it will also download the JDBC driver JAR automatically. Of course, this only will take place for a select list of drivers. The following steps outline how easy it is to use this wizard.

Database Pools

To create a new database pool, click on the link named “Using the Geronimo database pools wizard,” as shown in Figure 13-3.

Image from book
Figure 13-3: The beginning of the Database Pools Wizard

Create Database Pool (Step 1)

Upon clicking on the link to use the Geronimo Database Pools Wizard, the screen in Figure 13-4 is displayed.

Image from book
Figure 13-4: Step 1 of the Database Pools Wizard

Table 13-5 describes the available options on this screen.

Table 13-5: The First Available Options When Creating a Database Pool Open table as spreadsheet
Item | Description
Name of Database Pool | A unique name to identify the resource group in the Web console and to applications that intend to use the resource group.
Database Type | Select the appropriate database type from the list. If the correct database type is not listed, simply select Other from the bottom of the list.

After providing a name for the pool, click the Next button.

Create Database Pool (Step 2)

The second step to creating a database pool is to provide some metadata about the pool, including the selection of the driver name, the JAR file, the username and password, and so on. Figure 13-5 shows this screen.

Image from book
Figure 13-5: Step 2 of the Database Pools Wizard

Table 13-6 describes the parameters on this screen.

Table 13-6: More Available Options When Creating a Database Pool Open table as spreadsheet
Item | Description
JDBC Driver Class | The fully qualified package path for the JDBC driver class to use for this database pool. A default is provided based on the selection of database type on the previous screen, but this is easily changed using the input field on the form.
Driver Jar | Choose the appropriate JAR file for the pool that is being created. In this case, select PostgreSQL. The JAR must be placed in the repository directory on the filesystem. This means manually creating the directory hierarchy and placing the JAR file in the repository. After doing this task, simply refresh the page to grab the new list of available JAR files.
DB User Name | The database username.
DB Password | The database username’s account password.
Typical JDBC URL | Example format of the JDBC URL based on the database selected on the previous screen.
Port | The network port number on which the database is available.
Host | The name or IP address of the machine on which the database is running.
Database | The name of the database instance.

Because PostgreSQL is a very commonly used database, the JDBC drivers are widely available, so click the Download a Driver button to make Geronimo downloads the JDBC driver JAR.

Downloading a JDBC Driver

Using the screen in Figure 13-6, choose the database driver to download from the popup menu labeled Select Driver.

Image from book
Figure 13-6: Select the appropriate JDBC driver to download

Once the correct JDBC driver type and version combination are selected, click the Next button. A status screen may appear while the driver is being downloaded.

Create Database Pool (Step 2, Again)

Now the Step 2 screen is back, and it is populated with the JDBC driver JAR that was selected for down-loading, as shown in Figure 13-7.

Image from book
Figure 13-7: After downloading the JDBC driver and providing the required information

Fill in the rest of the information on this screen, and click the Next button to continue to Step 3.

Create Database Pool (Step 3)

In Step 3, the screen in Figure 13-8 will appear with the JDBC URL field populated appropriately.

Image from book
Figure 13-8: Completing the database pool configuration

Table 13-7 describes the parameters on this screen.

Table 13-7: The Final Pool Configuration Options Open table as spreadsheet
Item | Description
JDBC Connect URL | This is the JDBC URL to use to connect to the PostgreSQL database.
Driver Status | The status of the download in the previous step.
Pool Min Size | The minimum size of the database pool.
Pool Max Size | The maximum size of the database pool.
Blocking Timeout | Indicates the timeout period when waiting for a connection to be returned from a pool when all connections in a pool are in use and the pool has already reached its max-size. The default is 5000 milliseconds.
Idle Timeout | The amount of time a connection is allowed to go unused before it is automatically closed. The default is 15 minutes.

Once this information is filled in properly, the connection should be ready for a test.

Test Connection

To test the database pool, click the Test Connection button and the screen in Figure 13-9 will be displayed.

Image from book
Figure 13-9: Testing the JDBC connection

As long as the Test Result says Connected, the database pool is ready to be deployed. But before deploying the database pool, take a quick look at the deployment plan that is generated. To do this, click the button named Show Plan.

Show Plan

In the Deployment Plan text area is the XML plan that is created from the process of creating the database pool; it is displayed in Figure 13-10.

Image from book
Figure 13-10: The database pool plan

The XML plan displayed in the text area can be manually saved to a file and deployed using the command-line deployer. This allows for many additional uses of the file (such as being checked in to a version control system or manipulated manually).

Now the Deploy Pool button can be clicked to deploy the database pool.

Available Database Pools

Notice that the screen in Figure 13-11 now shows the ProGeronimoPool.

Image from book
Figure 13-11: The ProGeronimoPool

This screen indicates that the ProGeronimoPool is now ready for use.

Additional Functionality in the Geronimo Console

In addition to creating and configuring brand new database pools, the database pool wizard can also import existing database pool configurations from other application servers. This import process takes place by uploading the configuration files from other application servers to the Geronimo console. While this functionality is not outlined here, a different type of functionality is - the ability to work with a clustered PostgreSQL through the use of Sequoia.


Highly Available PostgreSQL with Sequoia

Sequoia is an Open Source project providing transparent database clustering, load balancing, replication, and failover via JDBC. As a follow-on project to ObjectWeb C-JDBC (http://c-jdbc.objectweb.org), Sequoia also offers a group-based communication project, a C++ client library with an ODBC driver and a management console. Sequoia accomplishes this via the Sequoia JDBC driver that forwards all database requests to one or more Sequoia controllers, which distributes these requests over a group of database instances. Sequoia accomplishes this by providing the concept of a redundant array of inexpensive databases (RAID). Figure 13-12 shows a high-level diagram explaining how Sequoia works.

Image from book
Figure 13-12: High-level architecture of Sequoia

In the Sequoia architecture, client applications make use of the Sequoia JDBC drivers instead of the database-specific JDBC drivers. This simple change hooks Sequoia so that the client applications are backed by a redundant array of databases without any changes to the client applications. The Sequoia controller hosts distributed host managers that host virtual databases. These virtual databases handle incoming JDBC requests from the Sequoia JDBC drivers via a request manager that provides load balancing across the actual databases on the back end via the various RAID configurations.

However, right in the middle is a recovery log that is stored in an instance of a HSQLDB database (http://hsqldb.org). HSQLDB is a 100 percent Java relational database that runs in a 100KB footprint and is designed to be embedded inside applications. The recovery log handles checkpoints and allows back ends to dynamically be added to a running cluster and to dynamically recover from a failure. You can download and find out more information on Sequoia from:

http://sequoia.continuent.org

Using Sequoia, the deployment plan for PostgreSQL can be made to make use of all of these features.

Configuring a Clustered PostgreSQL

For starters, the PostgreSQL deployment plan from the previous section is used as a starting point for the clustered database configuration. This deployment plan will hold almost all of the same data as the previous deployment plan, but with some changes for use with Sequoia. The changes are actually quite minimal, as shown in Listing 13-5.

Listing 13-5: The Clustered PostgreSQL Deployment Plan
Image from book
<?xml version="1.0" encoding="UTF-8"?>
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1">
  <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <dep:moduleId>
      <dep:groupId>postgresql</dep:groupId>
      <dep:artifactId>sequoia</dep:artifactId>
      <dep:version>1.1</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
    <dep:dependencies>
      <dep:dependency>
        <dep:groupId>sequoia</dep:groupId>
        <dep:artifactId>sequoia</dep:artifactId>
        <dep:version>2.9</dep:version>
        <dep:type>jar</dep:type>
        <dep:import>classes</dep:import>
      </dep:dependency>
    </dep:dependencies>
  <resourceadapter>
    <outbound-resourceadapter>
      <connection-definition>
        <connectionfactory-interface>
          javax.sql.DataSource
        </connectionfactory-interface>
        <connectiondefinition-instance>
          <name>ClusteredPostgreSQLDataSource</name>
          <config-property-setting name="UserName">
            geronimo
          </config-property-setting>
          <config-property-setting name="Password">
            geronimo
          </config-property-setting>
          <config-property-setting name="Driver">
            org.continuent.sequoia.driver.Driver
          </config-property-setting>
          <config-property-setting name="ConnectionURL">
            jdbc:sequoia://localhost:5432/test
          </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>15</idle-timeout-minutes>
      <match-one/>
     </single-pool>
    </connectionmanager>
   </connectiondefinition-instance>
  </connection-definition>
 </outbound-resourceadapter>
</resourceadapter>
Image from book

The first change is the artifact-ID to identify the fact that this is PostgreSQL with Sequoia. The next change is the addition of the Sequoia JDBC driver JAR dependency instead of the PostgreSQL JDBC driver. The last change is to the JDBC URL. It must change to work with the Sequoia driver. In addition to the Geronimo deployment plan, there is also configuration for Sequoia itself.

The Sequoia Configuration

To make Sequoia aware of the actual databases, Sequoia-specific configurations are necessary. Though getting Sequoia up and running is an exercise not detailed here, two configuration files are shown in Listings 13-6 and 13-7.

Listing 13-6: The postgresql-raidbl1-distributin-1.xml Sequoia Configuration File
Image from book
<?xml version="1.0" encoding="UTF8"?>
<!DOCTYPE SEQUOIA PUBLIC"-//Continuent//DTD SEQUOIA 2.3//EN"
"http://sequoia.continuent.org/dtds/sequoia-2.3.dtd">

<SEQUOIA>
  <VirtualDatabase name="myDB">
 <Distribution>
    <MessageTimeouts/>
 </Distribution>
   <AuthenticationManager>
      <Admin>
         <User username="admin" password=""/>
      </Admin>
      <VirtualUsers>
        <VirtualLogin vLogin="user" vPassword=""/>
      </VirtualUsers>
    </AuthenticationManager>
    <DatabaseBackend name="backend1" driver="org.postgresql.Driver"
url="jdbc:postgresql://node1/myDB" connectionTestStatement="select now()">
      <ConnectionManager vLogin="user" rLogin="TEST" rPassword="">
        <VariablePoolConnectionManager initPoolSize="10" minPoolSize="5"
maxPoolSize="50" idleTimeout="30" waitTimeout="10"/>
      </ConnectionManager>
    </DatabaseBackend>
    <DatabaseBackend name="backend2" driver="org.postgresql.Driver"
url="jdbc:postgresql://node2/myDB" connectionTestStatement="select now()">
      <ConnectionManager vLogin="user">
        <VariablePoolConnectionManager initPoolSize="10"/>
      </ConnectionManager>
    </DatabaseBackend>
    <RequestManager>
      <RequestScheduler>
         <RAIDb-1Scheduler level="passThrough"/>
      </RequestScheduler>
      <LoadBalancer>
         <RAIDb-1>
            <WaitForCompletion policy="first"/>
            <RAIDb-1-LeastPendingRequestsFirst/>
         </RAIDb-1>
      </LoadBalancer>
      <RecoveryLog driver="org.hsqldb.jdbcDriver"
        url="jdbc:hsqldb:hsql://localhost:9001" login="SA" password="">
        <RecoveryLogTable tableName="RECOVERY" idColumnType="BIGINT NOT NULL"
          vloginColumnType="VARCHAR NOT NULL" sqlColumnType="VARCHAR NOT NULL"
          extraStatementDefinition=",PRIMARY KEY (id)"/>
        <CheckpointTable tableName="CHECKPOINT"
          checkpointNameColumnType="VARCHAR NOT NULL"/>
        <BackendTable tableName="BACKEND"
          databaseNameColumnType="VARCHAR NOT NULL"
          backendNameColumnType="VARCHAR NOT NULL"
          checkpointNameColumnType="VARCHAR NOT NULL"/>
        <DumpTable tableName="DUMP" dumpNameColumnType="VARCHAR NOT NULL"
          dumpDateColumnType="VARCHAR NOT NULL"
          dumpPathColumnType="VARCHAR NOT NULL"
          dumpFormatColumnType="VARCHAR NOT NULL"
          checkpointNameColumnType="VARCHAR NOT NULL"
          backendNameColumnType="VARCHAR NOT NULL"
          tablesColumnType="VARCHAR NOT NULL"/>
      </RecoveryLog>
    </RequestManager>
  </VirtualDatabase>
</SEQUOIA>
Image from book
Listing 13-7: The postgresql-raidb1-distribution-1.xml Sequoia Configuration File
Image from book
<?xml version="1.0" encoding="UTF8"?>
<!DOCTYPE SEQUOIA PUBLIC"-//Continuent//DTD SEQUOIA 2.3//EN"
"http://sequoia.continuent.org/dtds/sequoia-2.3.dtd">

<SEQUOIA>
  <VirtualDatabase name="myDB">
 <Distribution>
    <MessageTimeouts/>
 </Distribution>
   <AuthenticationManager>
      <Admin>
         <User username="admin" password=""/>
      </Admin>
      <VirtualUsers>
        <VirtualLogin vLogin="user" vPassword=""/>
      </VirtualUsers>
    </AuthenticationManager>
    <DatabaseBackend name="backend3" driver="org.postgresql.Driver"
url="jdbc:postgresql://node3/myDB " connectionTestStatement="select now()">
      <ConnectionManager vLogin="user" rLogin="TEST" rPassword="">
        <VariablePoolConnectionManager initPoolSize="10" minPoolSize="1"
maxPoolSize="0"/>
      </ConnectionManager>
    </DatabaseBackend>
    <DatabaseBackend name="backend4" driver="org.postgresql.Driver"
url="jdbc:postgresql://node4/myDB " connectionTestStatement="select now()">
      <ConnectionManager vLogin="user"> <!-- assumes rlogin/rpassword identical to
vLogin/cPassword -->
        <VariablePoolConnectionManager initPoolSize="1"/>
      </ConnectionManager>
    </DatabaseBackend>
    <RequestManager>
      <RequestScheduler>
         <RAIDb-1Scheduler level="passThrough"/>
      </RequestScheduler>
      <LoadBalancer>
         <RAIDb-1>
            <WaitForCompletion policy="first"/>
            <RAIDb-1-LeastPendingRequestsFirst/>
         </RAIDb-1>
      </LoadBalancer>
      <RecoveryLog driver="org.hsqldb.jdbcDriver"
        url="jdbc:hsqldb:hsql://localhost:9001" login="SA" password="">
        <RecoveryLogTable tableName="RECOVERY" idColumnType="BIGINT NOT NULL"
          vloginColumnType="VARCHAR NOT NULL" sqlColumnType="VARCHAR NOT NULL"
          extraStatementDefinition=",PRIMARY KEY (id)"/>
        <CheckpointTable tableName="CHECKPOINT"
          checkpointNameColumnType="VARCHAR NOT NULL"/>
        <BackendTable tableName="BACKEND"
          databaseNameColumnType="VARCHAR NOT NULL"
          backendNameColumnType="VARCHAR NOT NULL"
          checkpointNameColumnType="VARCHAR NOT NULL"/>
        <DumpTable tableName="DUMP" dumpNameColumnType="VARCHAR NOT NULL"
          dumpDateColumnType="VARCHAR NOT NULL"
          dumpPathColumnType="VARCHAR NOT NULL"
          dumpFormatColumnType="VARCHAR NOT NULL"
          checkpointNameColumnType="VARCHAR NOT NULL"
          backendNameColumnType="VARCHAR NOT NULL"
          tablesColumnType="VARCHAR NOT NULL"/>
      </RecoveryLog>
    </RequestManager>
  </VirtualDatabase>
</SEQUOIA>
Image from book

Listings 13-6 and 13-7 set up four PostgreSQL database instances on four nodes to be clustered using Sequoia. These two configurations are almost identical except for two differences:

  1. The JDBC URLs for the PostgreSQL databases that are hosted on two separate nodes per configuration file for a total of four

  2. The connection pool manager configuration for each database

In addition to these two differences, these configuration files set up the RAID configuration and the recovery logs for each request manager. For more information on RAID configuration options and other features provided by Sequoia, see the Sequoia documentation. But the only thing left to do at this point is to deploy the configuration.

Deploying the Clustered PostgreSQL Deployment Plan

Deploying this plan is no different than deploying the nonclustered version of the plan. Interaction with the Geronimo deployer can be accomplished using either Maven or Ant, or a direct interaction can take place on the command line, using the shell script wrapper for the Geronimo deployer:

$ ./bin/deploy.sh --user system --password manager deploy \
  ./plan.xml \
  ~/.maven/repository/tranql/rars/tranql-connector-1.0.rar

    Deployed ClusteredPostgreSQLDataSource

Again, this output (upon successfully deploying the plan) is minimal. In addition to this message, the Geronimo Console can be used to determine what J2EE resource adapters are currently running.


Summary

This chapter outlined J2EE resource adapter deployment plans for JDBC resources. It began by outlining the PostgreSQL architecture to familiarize you with this popular Open Source database. Not only were the J2EE resource adapter deployment plan contents outlined, but also the default deployment plans for an embedded instance of Apache Derby and a plan for PostgreSQL were introduced as well.

Last, the use of the Sequoia clustering and high-availability tool for relational databases via JDBC was introduced. Sequoia’s architecture was briefly introduced before showing the necessary changes to the ClusteredPostgreSQLDataSource plan to make it work with Sequoia. As this chapter explained, J2EE resource adapter configuration is an important topic to understand in working with Geronimo.

Chapter 14 explores another high-demand feature of Geronimo - the ability to host Web services and expose EJBs as Web services.


Chapter 14: Deploying Web Services and CORBA Interoperation

Overview

The Geronimo server is quite versatile and can work with a large variety of access technologies. For example, users who are using Web browsers can access Web applications running on Geronimo, and thin-client applications can tap into the rich services provided by components (such as EJBs) running on Geronimo’s business tier. Recently, the ubiquity in using the Internet as the interconnection between businesses had made Web services technology extremely popular. The idea of Web services is to combine standards-based XML messages with the use of standard Internet transport protocols to deliver a robust service access and interoperation mechanism. Web services provide a platform for business-to-business and business-to-customer exchange of data and services over the Internet. The standards-based nature of Web services enable the software on both sides of the communication channel to be built with potentially different hardware systems and software.

Geronimo has built-in support of the deployment of Web services. With Geronimo, you can do the following:

  • Expose EJBs as Web services

  • Create and deploy J2EE-compliant, JAX-RPC-accessible Web services

  • Consume Web services from your Web-tier or business-tier components

In this chapter, you will discover how to configure Geronimo to expose an EJB as a Web service and how to deploy a component that supports JAX-RPC-based Web service access. Consuming Web services from a software component is primarily a development concern (utilizing the library support provided by Geronimo) and is outside the scope of this chapter.

While support of Web services open up Geronimo to a brave new world of access by diverse Web services clients, the Common Object Request Broker Architecture (CORBA) standard enables a Geronimo server to interoperate with a large universe of legacy systems and applications.

CORBA is a specification created by the Object Management Group (OMG), and has been established to enable software components created in different programming language, running on different operating systems, hosted on different hardware platforms to communicate and do useful work with one another. This goal of CORBA is somewhat similar to the goal of Web services. The differentiator is mainly in the audience that each technology addresses. Web services has a general audience, is based on standard Internet transport protocols and standard XML message formats. CORBA’s main focus is on users with existing legacy systems such as mainframe, minicomputer, real-time mission-critical systems, or super-computers. CORBA is based on an OMG-specified transport protocol passing binary formatted messages.

The Geronimo server is capable of the following:

  • Exposing an EJB as CORBA component, to be accessed by any CORBA client

  • Providing access to external CORBA systems and components

The second capability is a development issue and out of the scope of this chapter.

The chapter reveals how to configure and deploy an EJB using a Geronimo server that can be accessed as a CORBA component. This coverage includes a discussion of the CSIv2 security mechanism used by CORBA systems and how to configure secured access when using CORBA components.


Web Services Fundamentals

The technical field of Web services brings with it its very own set of terminology and jargons. Because of the modern heritage of Web services technology, this set of terminology is independent of those of Java development, server-side development, and even J2EE development.

As a Geronimo administrator, you will need to be versed in this terminology to communicate effectively with developers, application assemblers, and Web services users. This initial section of the chapter introduces the following:

  • The basic concepts in Web services, especially as they pertain to J2EE

  • Why Web services are very important

  • When and where Web services may be used

  • How the Geronimo server supports Web services

Anatomy of a Web Service

Fundamentally, a Web service operates through the exchange of messages, typically over the HyperText Transport Protocol (HTTP and its secured SSL-based variant).

Important

Although Web services can theoretically be carried over transport protocol other than HTTP/HTTPS, this is seldom done in practice.

HTTP is the enabling protocol of the World Wild Web and is well supported by the Internet, as well as today’s enterprise networks. Using HTTP as the transport protocol allows Web services to leverage the well-established network infrastructure to pass its messages. Other additional benefits of using HTTP as the transport protocol include the following:

  • Ability to communicate through firewalls (most firewalls are designed to pass HTTP traffic)

  • Support and diagnostic expertise is widely available

Unlike most network communication protocols (where the messages actually passed are in binary), the messages passed by Web services are in XML format. More particularly, the messages passed are formatted according to an industry standard called Simple Object Access Protocol (SOAP).

XML, SOAP, and JAX-RPC

Typically, a Web service client invokes a Web service by sending a message. This message specifies the details of the request, to be processed by the Web service. The Web service is responsible for sending the response back to the client after processing. Again, the response is sent back to the client via a Web service message. This pattern of interaction is often called a Request Response Message Exchange Pattern (MEP).

To process the incoming request, the Web service may elect to forward the message to another processor to do all or a portion of the work. The message format(s) specified by the SOAP protocol is designed to facilitate this style of message passing. Figure 14-1 shows the sequence of events that occurs when a Web service is invoked by a Web service client.

Image from book
Figure 14-1: Web service interactions

In Figure 14-1, the Web service client finds out about the feature of a Web service via its description. A Web service’s description is captured in an XML document, created to a World Wide Web Consortium (W3C) standard format called Web Service Description Language (WSDL).

The Web service client itself can be written in any programming language - it does not have to be Java. In fact, other operating system and platforms, such as Microsoft’s .Net on Win32 systems, have very rich support for creation of Web service client. Script languages such as Python and Grovvy can also be used to easily create Web service client.

Based on the description in the WSDL, the Web service client can then create properly formatted SOAP messages and send them to the Web service for processing. The features of a Web service are described in the form of a Web service interface. A Web service interface contains method names and parameter descriptions that enable the client to formulate messages to call methods on the interface. Again, the message is sent over HTTP.

On the Web service end, the service logic must decode the incoming SOAP messages. It then must process the message and formulate a SOAP message response. This response message is sent back to the client after processing, via the response mechanism of HTTP.

Note that Web services leverage the Request Response MEP inherent in the HTTP protocol (supported by all Web browsers) to invoke functionality exposed by the Web service. Instead of sending a request for a Web page (as in Web browsing), it sends a SOAP message that invokes Web service features. Instead of receiving a Web page as a response (as in Web browsing), it receives the processing response from the Web service.

It may appear from this description that creation of Web services and clients will require a lot of XML message parsing and manipulation. However, with the support of modern development tools, this is often not the case.

For example, if the Web service (or Web service client) is to be implemented using the Java programming language, a J2EE technology called Java API for XML Remote Procedure Call (JAX-RPC) can greatly simplify the creation of Web service and its associated client. JAX-RPC simplifies the process by completely automating, and, therefore, eliminating the need for the implementation code to parse XML. Figure 14-2 reveals how JAX-RPC does its work, in the context of a J2EE 1.4 compatible server such as Geronimo.

Image from book
Figure 14-2: JAX-RPC simplifies coding of Java Web services and Web service clients

In Figure 14-2, the JAX-RPC run-time support mechanism intercepts between the Java-based Web service client and the Java-based Web services implementation. Instead of working with a complex XML-based description of the Web service interface, Java code written to JAX-RPC can work with a programming interface in the Java programming language. This interface is called s Service Endpoint Interface (SEI).

Service Endpoint Interface (SEI)

The Web service client code, written in Java, in Figure 14-2 makes a local (non-networked) call to the method foo(). The method foo() is one of the method on the SEI Java interface. The client code need not know in advance that it is actually making a remote call to a Web service.

A JAX-RPC generated run-time component, a stub, intercepts this local call and prepares the SOAP message that is required to access the remote Web service running in Geronimo. After preparing the SOAP message, the stub sends the message via HTTP to the Web service running on Geronimo.

On the server end, the picture is quite similar. The Web service implementation is simply a software component written in the Java programming language that implements the SEI. Since the SEI is in Java, implementing the SEI is straightforward and does not require any XML parsing or tricky wiring performed by the service logic. Instead, the service logic only has to provide an implementation for the foo() method of the SEI.

Another JAX-RPC generated component, the interface proxy/tie component, will receive the SOAP message coming in from the Web service client, decode it, and then invoke the foo() method on Web service implementation. Return values, traveling from the Web service back to the client, are SOAP response messages that are created by the proxy/tie and received by the stub on the client side.

In summary, JAX-RPC provides standard Java-calling semantics support between Web service and Web service client writing in the Java programming language.

However, since the client side and Web service side of the JAX-RPC are essentially independent, JAX-RPC Web services can be consumed (invoked) by any Web service client - and not restricted to just Java-based clients. This will, of course, require the generation of a WSDL to be used by the non-Java-based client. JAX-RPC includes the capability to map SEI to WSDL. Figure 14-3 illustrates how JAX-RPC enables interoperation with non-JAX-RPC client.

Image from book
Figure 14-3: JAX-RPC interoperation with non-Java Web service clients

In Figure 14-3, the Java-based Web service logic component implements the foo() method on the SEI (a Java interface). JAX-RPC provides the Web service interface implementation and handles the parsing and decoding of SOAP messages. Meanwhile, any Web service client (even if they are not written using JAX-RPC or Java) can access the foo() method implementation by sending SOAP request message over HTTP to the Web service hosted in Geronimo.

Web Services and Geronimo

Right about now, you may be wondering how Web services relate to the Web-tier and business-tier components that have been discussed thus far in J2EE. The answer to this question also reveals how Geronimo supports Web services.

First, since Web-tier and business-tier components are all written in the Java programming language, they can readily take advantage of JAX-RPC’s ability to access any Web service. This means that application components in Geronimo, in business or Web tier, can consume external Web services.

More interesting to Geronimo server administrators, however, is the ability of Geronimo to expose functionality as Web services. Figure 14-4 shows the possibilities.

Image from book
Figure 14-4: Geronimo server exposing application components as Web services

In Figure 14-4, you can see two Geronimo-hosted application components being exposed as Web services. The EJB interface of a business-tier EJB (typically a stateless session bean) can be exposed via Geronimo as a Web service. Essentially, the SEI is the EJB interface.

Another application component, a Web tier servlet, can also expose a Java-based interface (a JAX-RPC SEI) that can implement a Web service to be hosted by Geronimo.

Internally, Geronimo makes use of the JAX-RPC server-side support provided by Apache AXIS to process the incoming SOAP requests.

Clients consuming the Web service must process the associated WSDL to understand how to invoke the Geronimo-hosted Web services. This WSDL must be generated by the developer from the SEI of the component.

Improtant

Note that Release 1.1 of the Geronimo server does not come with the tools required to create and generate code for JAX-RPC to WSDL mapping. As a result, you are likely to be working with WAR and EAR Web services modules that are created using another J2EE server’s tool such as those provided by Sun’s Java Web Service Developers Pack (JWSDP) ( http://java.sun.com/webservices/jwsdp/index.jsp ) reference implementation.

One important thing to note in Figure 14-4 is the grayed out component(s) called business logic implementation. What this figure attempts to show is the fact that the component that implements the SEI is typically not the only component involved in providing the Web service feature. In fact, the component providing the SEI is just the entry point component into the J2EE application logic-which in itself may involve tens or hundreds of other application components. An example may be a query Web service (handled by a servlet implementing the SEI) that utilizes the business Logic implementation to search a large airline reservation system. In this case, the Web service component is a front end, or faade, for the larger system.


Example 1: Deploying a Web Service WAR on Geronimo

The first example in this chapter shows how to configure and deploy a WAR file that contains a Web service on Geronimo. This particular WAR file, called progeronws.war, implements a JAX-RPC based Web service using a servlet.

The Web services has an endpoint interface that has one single method. This method returns the names of the authors of this book.

All of the code files in this Web service are in the com.wrox.progeronimo Java package. Table 14-1 summarizes the Java classes that make up the Web service and their responsibilities.

Table 14-1: Java Classes in the Servlet Web Service Example Open table as spreadsheet
Java Class | Description
AuthorsLocator | This is the JAX-RPC Service Endpoint Interface that is implemented by the Web service. It is a Java interface.
AuthorsLister | This is the actual implementation of the Web service. This Java class implements the AuthorsLocator interface.
AuthorWS, GetAuthors, GetAuthorsResponse | JAX-RPC helper classes that are generated by JAX-RPC tool. These classes are generated using the wscompile tool in Sun’s JWSDP mentioned earlier.

The actual JAX-RPC SEI for this Web service is AuthorsLocator. For reference, the Java code is shown in the following listing.

package com.wrox.progeronimo;

public interface AuthorsLocator extends java.rmi.Remote {
    public String [] getAuthors() throws java.rmi.RemoteException;
}

The only thing to note is that the interface has only one method called getAuthors().

Using this interface, and a Web services code generation tool (such as wscompile from the SUN JWSDP), the WSDL for the Web service can be generated. The JAX-RPC mapping file (containing WSDL to JAX-RPC mappings) can also be generated using the tool. Web services developers are familiar with these tools and can generate these two files from the SEI readily.

These two files are vital for the deployment of the Web service. Geronimo will parse these files and generate the necessary object serializer and tie classes to support the Web service during deployment. In this example, the two files are called:

  • AuthorsWS.wsdl

  • mapping.xml

These file are mainly of interest to developers and will not be listed here.

To properly deploy the Web service, the mapping.xml file must be placed under the WEB-INF directory of the WAR alongside the standard web.xml deployment descriptor. The WSDL file, on the other hand, should be placed into a wsdl subdirectory underneath the WEB-INF directory.

Also required is a J2EE Web service deployment descriptor called webservices.xml.

The webservices.xml Web Service Deployment Descriptor

To deploy one or more Web services in Geronimo, you must provide their description in a J2EE deployment descriptor called webservices.xml. This descriptor should be placed in the WEB-INF directory of the associated Web services WAR file.

The deployment descriptor provides a description of the following:

  • The Web services that will be deployed

  • Any dependencies of the Web services to be deployed

More specifically, it describes to the container, and ties together, the following:

  • The Web service description in the WSDL file

  • The JAX-RPC mappings in the mapping file

  • The JAX-RPC SEI that the Web service implements

  • The Java bean component that actually implement the Web service

The root element of this descriptor is a <webservices> element. This element contains one or more <webservice-description> subelements. The version attribute on this root element is required and must contain the value of “1.1”, as the following XML fragment illustrates:

<webservices xmlns="http://java.sun.com/xml/ns/j2ee" version="1.1">
...
</webservices>

Each <webservice-description> element inside the <webservices> root element describes a Web service that will be deployed by Geronimo, and it can have the subelements shown in Table 14-2.

Table 14-2: Inside the <webservice> Element Open table as spreadsheet
Subelement | Mandatory | Description
webservice-description-name | Yes | Provides a name to reference the Web service by.
wsdl-file | Yes | The WSDL file that describes the Web service to the container.
jaxrpc-mapping-file | Yes | The JAX-RPC mapping file that maps JAX-RPC to the Web service.
port-component | Yes | The description of the port component - the component that implements the service endpoint (that is, the Web service implementation).

The webservices.xml file for this example is shown in the following listing:

<?xml version="1.0" encoding="UTF-8"?>

<webservices xmlns="http://java.sun.com/xml/ns/j2ee" version="1.1">

    <webservice-description>
        <webservice-description-name>Wrox Author List</webservice-description-name>
        <wsdl-file>WEB-INF/wsdl/AuthorsWS.wsdl</wsdl-file>
        <jaxrpc-mapping-file>WEB-INF/mapping.xml</jaxrpc-mapping-file>
        <port-component>
            <port-component-name>AuthorsWS</port-component-name>
            <wsdl-port>AuthorsLocatorPort</wsdl-port>
            <service-endpoint
interface>com.wrox.progeronimo.AuthorsLocator</service-endpoint-interface>
            <service-impl-bean>
               <servlet-link>AuthorsServer</servlet-link>
            </service-impl-bean>
        </port-component>
    </webservice-description>

</webservices>

From this listing, you can see that the <port-component> element describes the Web service implementation in detail to the container. It can contain the subelements shown in Table 14-3.

Table 14-3: Subelements of the <port-component> Element Open table as spreadsheet
Subelement | Mandatory | Description
description | No | A human-readable description of the Web service.
display-name | No | A name used to identify the Web service in monitoring utilities and tools.
icon | No | The name of a file containing the graphical icon to represent the Web service when displayed in monitoring utilities and tools.
port-component-name | Yes | The name used to identify this port component-Web service implementation component.
wsdl-port | Yes | The name of the Web service port, as defined in the WSDL file.
service-endpointinterface | Yes | The JAX-RPC SEI Java interface that is implemented by the Web service implementation.
service-impl-bean | Yes | The actual Java component that implements the Web service.
handler | No | An optional hook for a callback before invocation of the Web service for custom security or other logic implementation.

The <service-impl-bean> element tells Geronimo the actual Java software component that implements the Web service. This component maybe a Web-tier servlet, or a business-tier EJB. You can specify either a <servlet-link> subelement or an <ejb-link> subelement, as shown in Table 14-4.

Table 14-4: Details of <service-impl-bean> Open table as spreadsheet
Subelement | Description
servlet-link | The link to the name associated with the servlet that implements the Web service.
ejb-link | The link to the name associated with the session EJB that implements the Web service.

The <handler> subelement is optional part of the <port-component> element. This element enables you to specify a callback handler method to process custom SOAP headers. A developer may want to do this to create customized security. If you do specify a <handler>, Table 14-5 describes the possible subelements.

Table 14-5: Content from the <handler> Element Open table as spreadsheet
Subelement | Mandatory | Description
handler-name | Yes | Name used to reference the handler.
handler-class | Yes | Fully qualified Java class name of the handler code.
init-param | No | Optional initialization parameters for the handler.
soap-header | No | Optionally specify the SOAP header that will be processed by the handler.
soap-role | No | Optionally specify the SOAP role of the handler.

The web.xml Deployment Descriptor for JAX-RPC Web Service

The standard J2EE Web application deployment descriptor, web.xml, will declare the Java class associated with the servlet and also an application context path for the servlet. The following listing shows web.xml for this example:

<?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">
    <description>
   Wrox Professional Geronimo Example
    </description>
    <display-name>Wrox Professional Geronimo Example</display-name>
   <servlet>
        <servlet-name>AuthorsServer</servlet-name>
        <servlet-class>com.wrox.progeronimo.AuthorsLister</servlet-class>
    </servlet>
    <servlet-mapping>
      <servlet-name>AuthorsServer</servlet-name>
      <url-pattern>/listerservice</url-pattern>
    </servlet-mapping>
</web-app>

The Java class that implements the Web service, as mentioned in Table 14-1, is the com.wrox .progeronimo.AuthorsLister class. This class implements the JAX-RPC SEI called AuthorsLocator. In this web.xml file, this class is named AuthorsServer via the <servlet> element. Look back at the webservices.xml deployment descriptor and you will see that this is the name that the <servlet-link> inside the <service-impl-bean> element refers to. This is the Java class that the container will look for to handle the Web services requests.

The <servlet-mapping> element maps the Web service servlet to the /listerservice context path. This path is relative to the root context of the application. The root context of the application can be controlled via a Geronimo-specific deployment plan named geronimo-web.xml. This plan is discussed in the sections “Specifying the Context Root for the Web Service” and “Deploying the Web Service,” later in this chapter.

Optional <service-ref> for Client Access to External Web Services

As mentioned previously, both Web tier and business-tier Geronimo components may be consumers of external Web services. Although this example does not involve external Web services, the following discussion explores this optional element in the web.xml file.

Like other reference elements, <service-ref> enables a client component to look up the Web service, by name via the container-supported JNDI API. The main purpose of the <service-ref> element is to fully describe, to the container, the properties of the Web service to be accessed by the client.

To configure access for an external Web service, you will need the following:

  1. The WSDL file for the external Web service

  2. The JAX-RPC mapping file (can be generated from the WSDL using a tool)

  3. The Java JAX-RPC Service Interface implemented by the Web service

The subelements allowed in the <service-ref> element include those shown in Table 14-6.

Table 14-6: The <service-ref> External Web Service Reference Open table as spreadsheet
Subelement | Mandatory | Description
service-ref-name | Yes | Reference name to the external service. This reference can be located via JNDI lookup by the client.
service-interface | Yes | The JAX-RPC service interface implemented by the Web service.
wsdl-file | Yes | The WSDL file that describes the Web service.
jaxrpc-mapping | Yes | The JAX-RPC mapping file that maps the Web services endpoint to JAX-RPC.

Creating a Cross-Server-Compatible Web Service WAR

Unlike other J2EE deployment descriptors, there is no Geronimo container-specific version of webservices.xml. This means that it is straightforward to create deployable WAR archives of Web services that can run on Geronimo or any other J2EE 1.4–compatible servers.

Important

There is one restriction for Geronimo that needs to be catered for when creating or generating the WSDL description file. The element in <wsdl:types> that describes the request message for an operation must have the same name as the operation itself. In this example, it would be the GetAuthors operation. Some WSDL generation tool may not fulfill this requirement, leading to the necessity to modify the generated WSDL file.

The example WAR file is created in a server-independent, J2EE 1.4–complaint manner, and should be deployable on other compatible container.

Specifying the Context Root for the Web Service

Finally, it is necessary to provide an application context root for the Web service. Like any other WAR deployment, this can accomplish by creating a Geronimo-specific deployment plan for the WAR. This plan can be geronimo-web.xml placed in the WEB-INF directory of the WAR, or it can be supplied separately to the deployer during the deployment of the WAR.

The following is the geronimo-web.xml deployment plan that is used to deploy the sample servlet-based Web services:

<?xml version="1.0" encoding="UTF-8"?>
<web-app   xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
    xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1">
 <sys:environment>
    <sys:moduleId>
      <sys:groupId>wrox</sys:groupId>
      <sys:artifactId>progeronws</sys:artifactId>
      <sys:version>1.0</sys:version>
      <sys:type>car</sys:type>
    </sys:moduleId>
</sys:environment>
    <context-root>/authorsws</context-root>
</web-app>

This plan places the root context of the Web service to /authorsws. Back in the web.xml deployment descriptor, the servlet that implements the Web service is mapped to the context path /listerservice. Combining the root context with the context path of the servlet, the Web service can be accessed at the following URL:

http://localhost:8080/authorsws/listerservice

Within the progeronws.war, the geronimo-web.xml file is already placed under the WEB-INF directory. This alleviates the need for an external plan during deployment of the Web service.

Deploying the Web Service

Geronimo does not have a special option to deploy a Web service. Instead, it relies on existing deployment mechanisms for WAR and EAR application archives.

To deploy the servlet-based Web service, all you need to do is to deploy the progeronws.war archive. This can be accomplished via the command line and by supplying the system/manager for username/ password:

deploy deploy progeronws.war

Or, you can use the Web console to deploy the WAR file, as shown in Figure 14-5.

Image from book
Figure 14-5: Deploying the Web service WAR using the Web console

Once deployed, you can try to access the WSDL of the Web service using the following URL:

http://localhost:8080/authorsws/listerservice?wsdl

If you get an XML file display in your browser similar to that in Figure 14-6, then the Web service has been deployed successfully.

Image from book
Figure 14-6: Accessing the WSDL of the Web service using a browser

Trying Out the Example with a Standalone Web Service Client

To actually invoke the getAuthors() method of the Web service, you will need a Web service client.

The creation and coding of a standalone Web service client is beyond the scope of this book. The code download includes a JAX-RPC-based client that can access the example’s Web service. You will find the source code and binaries in the client subdirectory.

To run this client, you must have the following:

  1. Apache Ant 1.6.5 or later installed (from http://ant.apache.org)

  2. The JWSDP downloaded and installed (from http://java.sun.com/webservices/jwsdp/index.jsp)

Find the build.properties file in the client directory and make sure that you edit this to set the first line to point to your JWSDP installation directory. See the highlight portion of the following build .properties file fragment:

jwsdphome=c:/jwsdp16
jwsdpshared=${jwsdphome}/jwsdp-shared
jaxphome=${jwsdphome}/jaxp
jaxrpchome=${jwsdphome}/jaxrpc
saajhome=${jwsdphome}/saaj
....

To run the client, first ensure that the Web service is deployed on Geronimo. Then, in the client subdirectory, enter the following command:

ant run

A successful run of the client will display the name of all three authors, obtained from the servlet-based Web service hosted on Geronimo. Figure 14-7 shows the output from the client.

Image from book
Figure 14-7: A successful run of the standalone Web service client

Now that you’ve successfully deployed a Web service implemented by a Web-tier servlet component, it is an opportune time to try a Web service implemented by a business-tier EJB. The next example exposes the interface of an EJB as a Web service.


Example 2: Deploying a Stateless Session EJB As a Web Service

The J2EE 1.4 specification includes the support for automatic exposure of a session EJB as a Web service. Geronimo has this capability built in.

This second example shows how to configure and deploy a session EJB as a Web service. The session EJB will be the session bean that you have used in Chapter 12. For more details on this application, please review Chapter 12. The focus in this example is on the additional pieces that are added to the application to expose the session EJB as a Web service.

The session bean supports one method called getAuthors() and returns the list of authors for this book. Each author’s name is returned as a Java String (containing the author’s name). The Web service interface and the JAX-RPC SEI are exactly the same as the one in Example 1. The Web service interface is described in the AuthorWS.wsdl file, and the JAX-RPC SEI is the com.wrox.progeronimo.Authors Locator interface.

However, the Web service implementation is no longer a servlet class. Instead, it is the com.wrox .progeronimo.AuthorBean class - which is a local session EJB in the example from Chapter 12.

Table 14-7 shows the additional Java classes added to the EJB example to support its exposure as a Web service.

Table 14-7: Java Classes Added to EJB to Support Its Exposure As Web Service Open table as spreadsheet
Component | Description
AuthorsLocator | The JAX-RPC SEI that the Web service implements.
AuthorWS, GetAuthors, GetAuthorsResponse | JAX-RPC support classes that are generated by JAX-RPC tool - these classes are generated using the wscompile tool from the JWSDP.

Adding the WSDL and JAX-RPC Mapping Files

Similarly to example 1, the WSDL and JAX-RPC mapping files are vital for Geronimo during deployment - it parses them and generates the required tie and serializer classes for Web service deployment.

Instead of placing them under WEB-INF, however, for an EJB JAR archive, they must be placed under the META-INF directory. More specifically, both the AuthorWS.wsdl and the mapping.xml files are placed under META-INF directory of the EJB JAR file. In this second example, the EJB JAR file is called progeron-ejbs.jar and is placed inside the progws2.ear archive.

Configuring for EJB-Based Web Service Implementation

Since you are using the same WSDL, JAX-RPC mapping, and same JAX-RPC SEI as in the first example, you can also use the same webservices.xml file. Ensure that you place the webservices.xml file in the META-INF directory of the EJB JAR. You do, however, need to make one single major change to the webservices.xml. The file is shown in the following listing, with the major change highlighted:

<?xml version="1.0" encoding="UTF-8"?>
<webservices xmlns="http://java.sun.com/xml/ns/j2ee" version="1.1">
    <webservice-description>
        <webservice-description-name>Wrox Author List</webservice-description-name>
        <wsdl-file>META-INF/AuthorsWS.wsdl</wsdl-file>
        <jaxrpc-mapping-file>META-INF/mapping.xml</jaxrpc-mapping-file>
        <port-component>
            <port-component-name>AuthorsWS</port-component-name>
            <wsdl-port>AuthorsLocatorPort</wsdl-port>
            <service-endpoint-
interface>com.wrox.progeronimo.AuthorsLocator</service-endpoint-interface>
            <service-impl-bean>
               <ejb-link>AuthorEJB</ejb-link>
            </service-impl-bean>
        </port-component>
    </webservice-description>
</webservices>

The highlighted major change tells Geronimo that the Web service is implemented by an EJB. The <ejb-link> element refers to the session EJB by name. The next section will show the EJB configuration in the ejb-jar.xml file, when the name of the session EJB is declared.

The other minor changes to the webservices.xml involve the META-INF directory (instead of WEB-INF from the WAR-based example).

Mapping a Session Bean to a Service Endpoint

To tell Geronimo that a session bean is actually used to implement a JAX-RPC SEI that corresponds to a Web service endpoint, you need to add the <service-endpoint> element to the <session> EJB description in the ejb-jar.xml J2EE deployment descriptor.

The ejb-jar.xml file from this example is shown in the following listing. The added <service- endpoint> element is highlighted.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans
2.0//EN'
'http://java.sun.com/dtd/ejb-jar_2_1.dtd'>
<ejb-jar>
  <enterprise-beans>
      <session>
          <display-name>Stateless Session Bean Local Interfaces</display-name>
          <ejb-name>AuthorEJB</ejb-name>
          <local-home>com.wrox.progeronimo.AuthorsHomeLocal</local-home>
          <local>com.wrox.progeronimo.AuthorsLocal</local>
          <service-endpoint>com.wrox.progeronimo.AuthorsLocator</service-endpoint>
          <ejb-class>com.wrox.progeronimo.AuthorBean</ejb-class>
          <session-type>Stateless</session-type>
          <transaction-type>Container</transaction-type>
      </session>
    </enterprise-beans>

</ejb-jar>

The <service-endpoint> element specifies the JAX-RPC SEI that is implemented by this session bean. Note that the Web service implementation class is always the EJB implementation class specified by the <ejb-class> element.

Note that the <ejb-name> contains the name of the EJB, and this is the name that is referenced in the webservices.xml’s <ejb-link> element.

Providing a Deployment Context for the Web Service

Next, you must tell Geronimo the root context used to address the Web service. For example, you may want to address the Web service at the following URL:

http://localhost:8080/ejbauthorsfinder

You must create a Geronimo-specific deployment plan called openejb-jar.xml and place that in the META-INF directory of the EJB JAR file. In this example, the openejb-jar.xml used is shown in the following listing:

<?xml version="1.0"?>
<openejb-jar   xmlns=" http://www.openejb.org/xml/ns/openejb-jar-2.1"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
    xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1">
<sys:environment>
    <sys:moduleId>
      <sys:groupId>wrox</sys:groupId>
      <sys:artifactId>progeronejbws</sys:artifactId>
      <sys:version>1.0</sys:version>
      <sys:type>car</sys:type>
    </sys:moduleId>
</sys:environment>
     <enterprise-beans>
        <session>
            <ejb-name>AuthorEJB</ejb-name>
            <web-service-address>ejbauthorsfinder</web-service-address>
        </session>
    </enterprise-beans>
  </openejb-jar>

The highlighted code segment uses the <web-service-address> element to specify the root context path for the deployed Web service -ejbauthorsfinder.

Trying Out the Example

First, deploy the enterprise application EAR file, called progws2.ear. This will deploy both the EJB-based application and the Web service.

To access the old EJB-based application, use the following URL:

http://localhost:8080/ProGeronimo/authors.cgi

The application uses the AuthorBean session EJB to obtain the list of authors and shows it using a JSP, as shown in Figure 14-8.

Image from book
Figure 14-8: The AuthorBean EJB-based application

Now, access the URL of the Web service, implemented by the same AuthorBean:

http://localhost:8080/ejbauthorsfinder?wsdl

You should see a display of the WSDL for the Web service.

To actually test out the Web service, you must run the standalone client supplied.

Change into the client directory. Assuming that you have Ant and JWSDP installed for the last example, you can run the client as follows:

ant run

You should see the standalone client accessing the EJB Web service and printing out names of the authors of this book - as it did in the first example.


CORBA Concepts

Common Object Request Broker Architecture (CORBA) is a long-established standard that enables interoperation between dissimilar computing systems.

This standard is described by specifics published by the Object Management Group (OMG), a global industry consortium consisting of hundreds of large enterprises, institutions, and product vendors.

CORBA versus Web Services: Similar Yet Different

CORBA is similar to Web services and JAX-RPC in the following ways:

  • CORBA allows software components to communicate with one another over a network.

  • CORBA allows software components written in different programming languages to communicate with one another.

  • CORBA allows software components running on different operating systems and hardware platforms to communicate with one another.

  • CORBA is an international standard supported by a very large body of products and service vendors.

  • CORBA clients make a local call to a stub object that forwards the actual call over the network to the server.

That’s where the commonality ends; CORBA is significantly different from Web services and JAX-RPC in the following ways:

  • CORBA does not use XML-based SOAP messages for communication. A CORBA message is well specified but in binary encoding.

  • CORBA does not operate over HTTP as its transport protocol. CORBA has its own General Inter-ORB Protocol (GIOP), with a specialization of it for TCP/IP networks called Internet Inter-ORB Protocol (IIOP).

  • CORBA requires a language-specific binding to be available before client or server code can be written in a specific programming language.

  • CORBA requires the service of a special component called an Object Request Broker (ORB) to work. Many ORB products are available - both commercial and Open Source.

  • CORBA is a matured standard that has withstood the test of time (over two decades) in the computing industry.

Because of the maturity of CORBA, it is often seen as one of the premier open interface technologies to the J2EE enterprise integration system tier. Specifically, CORBA is frequently used to access functionality built into legacy mainframe, microcomputer, or customer purpose processing subsystems. You can contrast this with Web services, a modern access technology focused around business-to-business and business-to-consumer application integration.

The next section covers some key concepts and terminology specific to CORBA interoperation, enabling you to communicate with CORBA developers during Geronimo administration tasks.

Interface Definition Language

A CORBA client application invokes the feature of a CORBA server component by calling methods on a published interface on the server component. This is identical in concept to the Web service SEI. However, instead of being described in WSDL, the interface is described in CORBA Interface Definition Language (IDL)

IDL is programming-language neutral. An IDL file can describe the interfaces and methods that are available from a CORBA service component. All CORBA implementations will provide tools that can convert the IDL to programming-language-specific bindings. A binding is essentially generated code that implements the stub and skeleton framework. Figure 14-9 shows the relationship between IDL and language bindings.

Image from book
Figure 14-9: IDL compiler and programming-language-specific binding

In Figure 14-9, the IDL file is processed by an IDL compiler to generate code (binding) in the supported programming language. The generated code is then compiled linked with the client’s (or server’s) logic code to access the CORBA object remotely. Creating a CORBA client requires a separate code-generation (from IDL) phase and then a compilation phase.

ORB and CORBA Services

During IDL code generation, the IDL compiler actually creates a stub object on the client side (similar to JAX-RPC for Web services) and then a skeleton object on the server side (similar to the tie of JAX-RPC).

Unlike JAX-RPC, however, the stub does not create SOAP messages, and it does not communicate with the skeleton directly. Instead, they talk to a CORBA system component called an Object Request Broker (ORB). The role of an ORB is to transparently mediate between the client and the services that are available to it. The CORBA client invokes the services as if they are local to the client. The stub object forwards the invocation information to the ORB. It is the ORB that actually locates the appropriate service physically and brokers the call. On the service end, the service logic is implemented against the generated binding’s skeleton object. The service object thinks that the call is local, but it is actually a forwarded call through the skeleton, from an ORB. One ORB may handle the call forwarding all by itself, or it may work with other ORBs in locating the service; this detail is opaque to the client and the service. Figure 14-10 shows the action of an ORB.

Image from book
Figure 14-10: CORBA ORB brokering a remote call

In Figure 14-10, the client’s local call to a method on the service interface is being intercepted by the stub- a part of the binding. The stub object passes the call to the ORB. The ORB, in turn, forwards the call to the service, potentially using the service of another ORB. The call is received at the service end by the skeleton binding code. This skeleton binding code invokes the service method locally within the service implementation.

The CORBA specification also includes a set of standard CORBA Services. Some of these services are mandatory, and are implemented by every compliant ORB vendor. For example, the Naming service, a service providing for a client to locate a remote CORBA component by name, is standard with every ORB implementation.

GIOP and IIOP

In early versions of CORBA, ORBs from different vendors were not able to communicate with one another. This posed a major problem for a supposedly universal, interoperable mechanism. As a major design goal of CORBA 2.x, all modern ORBs are now required to be interoperable with one another. This interoperation is achieved through a common over-the-wire protocol called General Inter-ORB Protocol (GIOP). GIOP specifies how ORBs must communicate over a network. When the network is a TCP/IP network (such as the Internet), a specialization of GIOP called Internet InterORB Protocol (IIOP) is used.

Simplifying Java-Based CORBA Interoperation

To support CORBA interoperation, Java has incorporated an ORB as part of its platform since the early days of JDK 1.1. The OMG group also views the Java platform as a very important server implementation vehicle and has worked with the Java community to improve the interoperability between CORBA and Java components.

Java’s native means to communicate between distributed Java components is Remote Method Invocation (RMI). RMI utilizes a proprietary Java Remote Method Protocol (JRMP) to communicate between components. To facilitate interoperation with CORBA-based components, RMI-IIOP as introduced with JDK 1.2. RMI-IIOP utilizes IIOP as the protocol between distributed Java components, instead of the proprietary JRMP. As a result, a Java-based client can access CORBA service objects on any platform using RMI styled semantics. Using RMI-IIOP, the Java programming language can also be used to create service components that can be exposed as CORBA components - without having the hassle with binding generation from IDL and source-based compilation. Figure 14-11 shows how RMI-IIOP facilitates CORBA interoperation.

Image from book
Figure 14-11: RMI-IIOP supporting both CORBA client access and RMI client access

In Figure 14-11, the business-tier EJB component is exposed via RMI-IIOP as a CORBA component supporting the EJB interface. In fact, this is what Geronimo as a J2EE 1.4 compatible server is able to do - exposing a J2EE EJB as a CORBA component - to be accessed by CORBA clients.

Non-Java CORBA clients can generate an IDL file from the exposed RMI interface using the rmic tool supplied with JDK 1.4. This IDL file can then be used to generate language-specific binding in the creation of a client. Java-based clients, on the other hand, can use pure RMI syntax to access the CORBA component via IIOP.


Example 3: Exposing a Session EJB As a CORBA Component

You can expose a session EJB as a CORBA component by configuring with a Geronimo-specific deployment plan for the application. This example shows how to configure and deploy such an EJB component.

To keep things simple, the EAR application that is used is once again the authors list application from Chapter 12.

This example does the following:

  • Creates a geronimo-application.xml plan to deploy the AuthorsBean EJB as a CORBA component

  • Includes a CORBA client application, running under the Geronimo client application container, to test the exposed EJB

One of the most important things to get just right when exposing a CORBA component is the access security configuration. Geronimo CORBA supports CSIv2, explained next.

CORBA 2.3 Security

To implement a secure communication channel between CORBA components over heterogeneous networks, the CORBA 2.3 specification includes Common Security Interoperability, Version 2 (CSIv2). CSIv2 is a comprehensive specification that can be used to negotiate and implement application-specific levels of security for distributed systems. The unique property of CSIv2 is that it can be implemented over a large variety of transport layer protocols and requires only a single message exchange to establish a security context. Geronimo’s CORBA support includes support of CSIv2.

Geronimo Support for CSIv2 Security

The CSIv2 implementation in Geronimo is encapsulated in several GBeans. These GBeans are a mandatory part of Geronimo’s CORBA communications stack. You must configure these CSIv2 GBeans appropriately when exposing/deploying CORBA components in Geronimo.

Figure 14-12 shows the security interactions in a CORBA 2.3 network.

Image from book
Figure 14-12: The CORBA CSIv2 implementation

In Figure 14-12, the server side of the CORBA implementation has a Target Security Service (TSS) GBean. The client side of the CORBA implementation has a Client Security Service (CSS). Together, the CSS and TSS GBeans implement the CSIv2 negotiation of security required. Figure 14-12 also shows how the CSIv2 implementation can achieve required data secrecy, integrity, authentication, and authorization requirements.

Configuring Server-Side CSIv2 Security

Security negotiation occurs between Geronimo CSS and TSS components. To expose an EJB as a CORBA component, you must select the appropriate TSS component instance. Each TSS component instance implements a certain level of required security. Table 14-8 shows the available TSS implementation in Geronimo 1.1.

Table 14-8: CSIv2 TSS GBean Available in Geronimo 1.1 Open table as spreadsheet
TSS GBean Name | Security Enforced
IdenityTokenNoSecurity | The TSS implementation requires no additional CSIv2 security enforcement. Communication is over standard TCP channel.
SSLClientCert | Client is required to authenticate via client certificate. Communication is over SSL for data encryption and integrity.
SSLClientPassword | Client is required to authenticate with password. Communication is over SSL for data encryption and integrity.
SSLClientCertIdentityToken | Combines client certificate authentication with identity token. Communication is over SSL for data encryption and integrity.
SSLIdentityToken | No additional client authentication required beyond an identity token. Communication is over SSL for data encryption and integrity.

In the geronimo-application.xml plan, as a child element of the <session> bean, the <tss-link> element indicates to the Geronimo server your selected TSS level of security. The following listing shows the use of the <tss-link> element in the example.

<?xml version="1.0" encoding="UTF-8"?>
<application
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1">
      <environment>
      <moduleId>
        <groupId>geronimo</groupId>
        <artifactId>progeroncorba</artifactId>
        <version>1.0</version>
        <type>car</type>
      </moduleId>
      <dependencies>
        <dependency>
          <groupId>geronimo</groupId>
          <artifactId>j2ee-corba</artifactId>
          <type>car</type>
        </dependency>
      </dependencies>
    </environment>

    <module>
        <ejb>authors-ejbs.jar</ejb>
        <openejb-jar
            xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1">
            <enterprise-beans>
               <session>
                   <ejb-name>AuthorEJB</ejb-name>
                   <jndi-name>AuthorEJB</jndi-name>
                   <tss-link>IdentityTokenNoSecurity</tss-link>
               </session>
            </enterprise-beans>
        </openejb-jar>
    </module>
    ...

In this example, the TSS component selected by the <tss-link> component will allow client access with no security other than an identity token. There is no encryption of data sent over the network.

Configuring Client-Side CSIv2 Security

On the client side, you will need to select a CSS component instance. Table 14-9 shows the available instances with Geronimo 1.1.

Table 14-9: CSIv2 CSS GBean Available in Geronimo 1.1 Open table as spreadsheet
CSS GBean Name | Security Enforced
NoSecurity | Attempt to access server with no security. Data will be sent over unencrypted TCP.
NoSecurityIdentityTokenPrincipal | Attempt to access server with an identity token. Issue the token based on the security principal.
NoSecurityIdentityTokenCert | Attempt to access server with an identity token scheme. Issue the token based on a client certificate.
SSLIdentityTokenCert | Access server with identity token based on client certificate. Use SSL for data communications.
SSLIdentityTokenPrincipal | Access server with identity token based on security principal. Use SSL for data communications.
SSLClientPassword | Authenticate to server with password. Use SSL for data communications.
SSLClientCert | Authenticate to server with client certificate. Use SSL for data communications.

The selection of CSS GBean is specified in the deployment plan for the client application.

For Geronimo release 1.1, the CSS and TSS GBeans in Table 14-8 and 14-9 are actually not preconfigured in the geronimo/j2ee-corba/1.1/car or the geronimo/client-corba/1.1/car modules. Instead, you must configure these GBeans explicitly in your deployment plans. See the source code download for details on this GBean configuration. This is likely to change in a future subrelease, as Geronimo adapts to other ORBs beyond the SUN JDK ORB.

CORBA Client Support

CORBA client can be written in any programming language on any supported OS or hardware platform. To access the Geronimo hosted CORBA component from another system, you need to do the following:

  • Obtain a CORBA 2.3–compatible ORB on that system that supports CSIv2

  • Generate a CORBA IDL from the Java access interface, and then use the IDL to generate a language-specific binding on the supported platform

The creation of a client on a non-Java platform is out of the scope of this example. In this example, things are kept simple by using a Geronimo-hosted client.

A Geronimo-hosted CORBA client can take advantage of the following:

  • Application client container support provided by Geronimo for its deployment and configuration

  • JNDI-based CORBA naming service lookup provided by the container

  • RMI-IIOP support, eliminating the need to work through IDL or CORBA Java binding

The client application in this example takes full advantage of Geronimo as a client container, simplifying the configuration and coding.

Improtant

As of Geronimo 1.1, the client container support will only work when the client is running on the same machine as the server. This restriction will be eliminated in future versions of Geronimo, check the release notes for more information.

The geronimo-application.xml configures the client application in a <module> element, including the selection of CSS component. The following listing shows the client application configuration in this deployment plan.

    ...
   <module>
        <java>authors-clientapp.jar</java>
        <application-client xmlns="
http://geronimo.apache.org/xml/ns/j2ee/application-client-1.1"">
           <client-environment>
             <moduleId>
               <groupId>wrox</groupId>
               <artifactId>corbaclient</artifactId>
               <version>1.0</version>
               <type>car</type>
             </moduleId>
             <dependencies>
               <dependency>
                 <groupId>geronimo</groupId>
                 <artifactId>client-corba</artifactId>
                 <type>car</type>
               </dependency>
             </dependencies>
            </client-environment>
            <server-environment>
        </server-environment>            <ejb-ref>
               <ref-name>AuthorServer</ref-name>
               <ns-corbaloc>corbaloc::localhost:1050/NameService</ns-corbaloc>
               <name>AuthorListEJB</name>

            <css-link>NoSecurity</css-link>
            </ejb-ref>

         <realm-name>client-properties-realm</realm-name>
            <callback-handler>
com.ibm.dw.geronimo.corba.client.SecurityCallbackHandler
            </callback-handler>
        </application-client>
    </module>
      ...

The highlighted line shows the selection of the CSS GBean instance via the <css-link> element. Note that the <ejb-ref> reference the AuthorListEJB defined in the server’s configuration. This allows the client code to look up the EJB via the <ref-name> using JNDI.

Specifying Dependency on Parent Modules

To ensure that you can find the TSS and CSS GBean component when you deploy the example, you must ensure that you set <dependency> in the environment to the appropriate CORBA configurations. More specifically, in this example, the EJB server component has a parent module of geronimo/ j2ee-corba/1.1/car. This parent configuration is where the TSS beans are configured.

<application
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1">
      <environment>
      <moduleId>
        <groupId>geronimo</groupId>
        <artifactId>progeroncorba</artifactId>
        <version>1.0</version>
        <type>car</type>
      </moduleId>
      <dependencies>
        <dependency>
          <groupId>geronimo</groupId>
          <artifactId>j2ee-corba</artifactId>
          <type>car</type>
        </dependency>
      </dependencies>
    </environment>

For the client, the dependency is geronimo/client-corba/1.1/car.

<application-client xmlns=" http://geronimo.apache.org/xml/ns/j2ee/application-
client-1.1"">
           <client-environment>
             <moduleId>
               <groupId>wrox</groupId>
               <artifactId>progeroncorbaclient</artifactId>
               <version>1.0</version>
               <type>car</type>
             </moduleId>
             <dependencies>
               <dependency>
                 <groupId>geronimo</groupId>
                 <artifactId>client-corba</artifactId>
                 <type>car</type>
               </dependency>
             </dependencies>
            </client-environment>

This is all that is required to expose the EJB for CORBA access and to configure the client.

Configuring ORB Parameters via config.xml

The CORBA support components in Geronimo are GBeans. Like all other GBeans, they have configuration attributes that can be overridden in the config.xml file.

The standard config.xml comes with default values for CORBA components that work well with SUN JDK 1.4’s built-in ORB (supported by Geronimo 1.1).

For example, the TCP port used by the CORBA Naming Service can be modified in config.xml (with Geronimo server turned off) by modifying the following bolded lines.

...
<module load="false" name="geronimo/j2ee-corba/1.1/car">
    <gbean name="NameServer">
      <attribute name="dbDir">var/cosnaming.db</attribute>
      <attribute name="port">1050</attribute>
    </gbean>
    <gbean name="Server">
      <attribute name="args">-ORBInitRef,
NameService=corbaloc::localhost:1050/NameService</attribute>
    </gbean>
    <gbean name="UnprotectedServer">
      <attribute name="args">-ORBInitRef,
NameService=corbaloc::localhost:1050/NameService</attribute>
    </gbean>
    </module>
...

Trying Out the Example

The geronimo/j2ee-corba/1.1/car module is not started by default in Geronimo 1.1. You must start this before you can deploy the example. To start this module, you can do one of the following:

  • Use the Web console or command-line deployer to start the module while the server is running, and then restart the Geronimo server

  • Shut down the server, edit the config.xml file to remove the load=false attribute on the module, and then start the Geronimo server

In either case, you should see the geronimo/j2ee-corba/1.1/car module started (on the Web console, or use the list-module command of the deployer) after the restart of the Geronimo server.

To deploy the authorlister.ear archive, where both the server and client are bundled, you can use the following command:

deploy deploy authorlister.ear geronimo-application.xml

Or, you can use the Web console to deploy authorlister.ear with the geronimo-applications .xml plan.

Note that all of the CORBA-specific configurations are isolated to the geronimo-application.xml deployment plan. This keeps the authorlister.ear generic and deployable on other servers. Since the geronimo-application.xml is an external deployment plan, you can, in fact, use any name for the file.

To run the client application, use the following command:

java -jar bin/client.jar wrox/progeroncorbaclient/1.0/car

You should see the client accessing the CORBA bean over RMI-IIOP.


Summary

Geronimo provides rich support for the creation and deployment of Web services. The built-in J2EE 1.4 support for JAX-RPC-based Web services allows Web services to be coded in pure Java without XML parsing code. This simplifies the creation of Web services and Web service clients to be hosted in Geronimo.

Web services in Geronimo can be the following:

  • A Web-tier servlet that implements the service logic and exposed by Geronimo as Web service

  • A business-tier EJB that is exposed as a Web service by Geronimo

In either case, Geronimo will generate the required tie classes and serializer classes dynamically. You will need to supply the following:

  1. The JAX-RPC SEI that the service logic (or EJB) implements

  2. The WSDL description of the Web service endpoint

  3. A JAX-RPC mapping file that describes mapping of WSDL elements

In most cases, these files can be generated directly using tooling such as the SUN JWSDP. Geronimo tooling currently does not generate these files.

Exposure of EJB as CORBA component is also supported by the Geronimo server. No change in the actual EJB coding is required. You can simply create a custom deployment plan with the following:

  • <tss-link> element to select the level of CSIv2 server-side security you want

  • Create a dependency on the geronimo/j2ee-corba/1.1/car module

The Geronimo application container can be configured to host CORBA clients that access CORBA components via RMI-IIOP. You have configured such a client for the EJB CORBA implementation in this chapter.

Security, such as CORBA’s CSIv2, is a very important pervasive aspect in modern server systems. Geronimo has robust J2EE 1.4 compatible security support built into its architecture. Chapter 15 takes an in-depth look at Geronimo security.


Chapter 15: Security

Overview

As a J2EE server, Geronimo needs to manage the execution of a variety of software components on behalf of many users. Great care is taken to ensure that a user can only access the allowable code, system resources, and data. This access control is performed through Geronimo’s flexible security system.

The basic facets of J2EE security serve some real practical purposes, including the following:

  • Determining if you are who you claim to be - this is called authentication.

  • Enabling you to access only the resources that you are explicitly allowed to - this is called authorization.

Obviously, Geronimo must authenticate you before it can authorize you to access specific resources.

Authentication and authorization in Geronimo leverage the features of the Java Authentication and Authorization Service (JAAS) and Java Authorization Contract for Containers (JACC) API specifications.

Geronimo provides a rich set of configurable components, together with a robust security model, allowing you to flexibly adapt the system to your specific security requirements.

This chapter explores how Geronimo delivers on this flexibility and adaptability through the Geronimo security architecture.

Key security components in this architecture, as well as their model of interaction and configuration, are covered in detail within this chapter. Concepts and components coverage includes the following:

  • Security realms

  • Login modules

  • Login domains

  • J2EE security descriptor

  • Geronimo-specific security descriptor

You will see how to apply Geronimo security in your applications by creating customized security realms and configuring security descriptors in your deployment plans.

After reading this chapter, you will have a solid understanding of how security works in Geronimo and how to effectively secure your applications.

Important

Any configurable component in Geronimo is represented internally by a GBean (Geronimo Bean). The terms component and GBean will be used interchangeably throughout this chapter. These components are configurable in Geronimo deployment plans using XML elements.


Importance of a Security Subsystem

A security subsystem is one of the most critical components of a J2EE application server. Writing distributed applications can open many possible exploits into accessing sensitive data and logic. The more complex your applications become, the greater the chance for introducing an exploit.

Not properly securing your applications can potentially result in catastrophic consequences, leading anywhere from monetary losses to lost customers and legal implications. Securing your applications and knowing how to properly configure the security components is what ultimately protects your data, intellectual property, and business logic.

Geronimo provides a set of security components that follow proven and established Java security standards, so that you can secure your applications, and limit the possibilities of an exploit.

The Geronimo security architecture is based on JAAS and JACC. In the following discussions, a certain level of familiarity with the concepts and operation of JAAS and JACC is assumed. Readers unfamiliar with these Java specifications are encouraged to review their reference documentation at the following URLs:

  • JAAS - http://java.sun.com/products/jaas/reference/docs/index.html

  • JACC - http://java.sun.com/j2ee/javaacc/index.html

All JAAS and JACC concepts will be briefly introduced before they are applied in the discussion, and your familiarity with them will help you to quickly grasp the important role they play in the greater Geronimo Security Architecture.


Geronimo Security Architecture

The security model of Geronimo can be relatively straightforward when you consider that the end goal is to control the access to the applications that you develop. The cornerstones of this model are the two well-known security aspects: authentication and authorization.

Authentication

First, before enforcing any security policies that you may have, you must authenticate your users - making sure that they are who they claim to be. This can be as simple as checking user ID and password against a password file, or it may be as complex as requiring identification via an iris scan with a password and an ID badge.

As you may have noticed, there are at least as many ways to authenticate a user as there are operating systems - most requiring you to log on to the system before using it. In fact, authentication systems and standards exist all over the map. And they seem to be invented and adopted, and then stay around forever. Users don’t seem to take to migration between authentication systems lightly.

Furthermore, to be totally flexible, the concept of a living-and-breathing user must be abstracted to that of a security principal. This abstraction allows security policies to be enforced against tasks that are executed not directly by an authenticable human (for example, daemon processes that run regularly). It also allows the server to access system resources and call services on behalf of (acting as) specific users. In Geronimo security speak, a security principal supplies a credential to authenticate itself. This is analogous to a user supplying a password or biometrics for authentication.

Rich authentication capabilities are already built into the modern Java platform. Java Standard Edition 1.4 (which is an integral part of J2EE 1.4) already includes an authentication subsystem that accepts Pluggable Authentication Modules (PAMs) to carry out actual authentication. This flexible plug-in-based authentication subsystem is part of JAAS 1.0.

Authorization

Authorization (the act of enforcing access according to authenticated security principals) is the other cornerstone facet of the security architecture. A set of access rules must be declared, maintained, tracked, and enforced by Geronimo to ensure that unauthorized access is not allowed under any circumstance. This set of access rules forms a security policy. Authorization in Geronimo can be controlled by declaring security policies, and having the container enforce these policies during run time.

Using a security policy, you can allow authenticated principals to access different parts of the application based upon the kinds of roles they play (such as administrator, manager, supervisor). Often, you do not know ahead of time the set of principals who will be accessing your application. Authorization based on roles (instead of individual users) allows you to secure your application without knowing all the possible principals in advance. Access control is not limited to parts of a Web application, but also applies to most other Geronimo-managed resources (such as database connections, message queues, and external EJBs). These are frequently referred to as protected resources.

As a J2EE server, Geronimo supports both declarative security and programmatic security. Declarative security allows security policies to be added to modules via a security descriptor within deployment plans. These policies are enforced by Geronimo and can be modified without changing the code of the modules. Programmatic security, on the other hand, is the explicit code fragments that run and perform access checks. Policies enforced by programmatic security are hard-coded into the application and can not typically be modified without a recompilation of the code. The focus in this chapter is on declarative security. Consult a J2EE development book if you are interested in the details of programmatic security support.

Under the Geronimo security architecture, you must first create a security realm on the server and then use it to supply authentication and authorization services for your protected resources. A security realm is always associated with a set of login domains. Both security realm and login domains are concepts that are explored in detail in the next section.

Geronimo’s security architecture is completely componentized. Security components such as security realms and login modules are implemented as GBeans (server software components managed by Geronimo). These GBeans are readily configurable via XML descriptor elements in deployment plans. They can be configured flexibly to secure your application.

As an administrator, it is important to become familiar with the configuration of the Geronimo security components and their model of interaction.

Security Realms and Login Domains

A security realm is made up of one or more login domains and an authentication policy. Each of the login domains can represent a different source of authentication information. The authentication policy controls how authentication must succeed before the security principal is considered to be authenticated.

A login domain represents a physical source of authentication information (typically containing user, credentials, and user-to-group mapping). Physically, it may use an SQL database with user/password information, an LDAP server, a properties file read into memory, or other storage of user/group data. When a user successfully authenticates against a login domain (using login modules, covered in the next section), the user is represented internally (within the Geronimo server) by a set of javax.security .Principal objects. This set typically includes a user object and one or more group objects. The group objects represents the roles that the user plays (or groups that the user belongs to). These are the roles/ groups that are typically used in deployment plans and J2EE deployment descriptors to protect application resources.

For example, in order for you to be granted access to your employment record, you may need to be authenticated successfully against your department’s Windows 2003 Server authentication (NTLM) server (login domain #1), as well as the Human Resource department’s LDAP-based system (login domain #2). You can configure a security realm consisting of two login domains to accomplish this. Figure 15-1 illustrates this scenario.

Image from book
Figure 15-1: Security realm

During the configuration of a security realm such as the one shown in Figure 15-1, you can specify in the authentication policy that authentication will only succeed if every login domain is authenticated successfully (in other words, all must pass; a single login domain authentication failure causes full failure to access resources), or you can specify that only one success is sufficient to authenticate the security principal. In Geronimo, enforcement of this authentication policy is available via the custom configuration of login modules within a security realm.

You can run Geronimo on a Java Virtual Machine (JVM) supporting either the J2SE 1.4 or JSE 5 Java platform. Both of these platforms have JAAS 1.0 built in. Since JAAS 1.0 already includes PAMS implementations to authenticate against a variety of common systems, Geronimo’s designers took advantage of this and based login domain implementation on these pluggable authentication components. These components are called JAAS login modules (not to be confused with login domains).

JAAS Login Modules

To successfully configure login domains - and create security realms - you must be able to configure some physical authentication modules. These authentication modules are the JAAS login modules, so you will need to be able to configure JAAS.

In Geronimo, the pluggable authentication modules in JAAS (login modules) are represented by configurable LoginModule components. You can configure a set of configuration entries that relates an application name or realm name to a set of LoginModules.

A LoginModule is a physical authenticator. It handles the interaction between the client and a specified login domain. Physical authentication is always performed through one of these LoginModules. Each LoginModule can represent a login domain and is the key piece of actual code that validates and verifies the user’s credentials against that domain.

In Geronimo, several types of security components can reference LoginModules. These include the following:

  • GenericSecurityRealm

  • ServerRealmConfiguratioEntry

  • DirectConfigurationEntry

By far, the type that will be used most frequently is GenericSecurityRealm. This component, of course, represents a generic security realm.

The configuration of all of these components will be discussed in detail later in this chapter. The focus of attention in the next section will be on GenericSecurityRealm,.

The GenericSecurityRealm

The GenericSecurityRealm represents a plain-vanilla security realm and can be used as a model in creating your own custom security realm. The GenericSecurityRealm configuration entry lets you configure multiple LoginModules, allowing you to chain them together (see Figure 15-2).

Image from book
Figure 15-2: JAAS Security GBean relationships

JAAS Login Modules Chaining

Chaining is an extended concept of JAAS and lets you do powerful things, such as have multiple login domains to authenticate against, or plug in specialized utilities that can enable logging or lock out bad authentication attempts.

Take a careful look at Figure 15-2. A GenericSecurityRealm contains a reference to a JaasLoginModuleUse component. This component, in turn, contains a reference (or acts as a wrapper) to a single LoginModule and its JAAS controls flag. The JaasLoginModuleUse component can also hold a reference to another JaasLoginModuleUse component (configured via the next attribute). This is the mechanism that allows chaining of multiple LoginModules within a realm or configuration entry.

Geronimo Server JAAS Configuration

The GeronimoLoginConfiguration GBean is responsible for representing the entire login configuration for JAAS. It will maintain references to all of the different ConfigurationEntryFactory GBeans, which includes the GeronimoSecurityRealm, ServerRealmConfiguratioEntry, and DirectConfigurationEntry GBeans.

The JaasLoginService GBean is the component that handles the interface between the client and the Geronimo security realm. This GBean handles both the server-side and client-side interaction for authentication, and acts as a bridge between the two.

JAAS Login Coordinator

Underneath the hood of the GeronimoSecurityRealm and JaasLoginService, the interaction is managed by a single component called the JaasLoginCoordinator. This component is actually a LoginModule. The GeronimoSecurityRealm component creates it at run time and stuffs this component into the login configuration.

This JaasLoginCoordinator is secret exit for the client or server to call the JAAS API. It acts as a proxy to the other LoginModules in the chain and handles the standard JAAS API calls to login(), initialize(), commit(), abort(), and logout(). In other words, whenever these methods are called from the client, the JaasLoginCoordinator ‘s version will be called, and proxy the calls for all of your other configured LoginModules. The interesting aspect of this is that the client thinks it is talking to a single LoginModule, when, in reality, it is simply acting as an adapter to the JaasLoginService and the other chained LoginModules.

Figure 15-3 shows the interaction between the client and the LoginModules. The client in these instances generally represents a remote process or a Web application. This example shows a configuration that contains a chain of two LoginModules, one for LDAP and one for a MySql database. When the JAAS API calls login(), it invokes the JaasLoginCoordinator as a primary LoginModule. The JaasLoginCoordinator proxies the calls for each of the LoginModules in the configuration as a chain by working through the JaasLoginService GBean by calling its performLogin() method. The JaasLoginService then passes the original JAAS login() call onto each of the LoginModules.

Important

Each GeronimoSecurityRealm creates and has its own JaasLoginCoordinator, so each JaasLoginCoordinator is specific to a single security realm.

Image from book
Figure 15-3: JaasLoginCoordinator proxying calls to LoginModules

The operations of the JaasLoginCoordinator occurs under the hood and does not affect how you configure Geronimo security realms. This exploration serves to provide insight into the actual operation of the security system.

JMX Remoting Login Service

The JaasLoginService represents the Geronimo Login Service API that enables access to the LoginModules. For in-container access, the JaasLoginCoordinator acts as the bridge between the client and the security realm through the JaasLoginService. This allows authentication by any application components running within the same JVM as the Geronimo server. Sometimes separate Geronimo instances, each running in its own JVM, may need to use a common authentication service. For example, you may want to host EJBs in one Geronimo instance, and the Web tier (Tomcat) on another Geronimo instance. In these cases, Geronimo needs to support remote access to the JaasLoginService.

Geronimo accomplishes this by exposing a JMX connector GBean and a server wrapper around the JaasLoginService. In the Geronimo default security deployment plan, the JMXService GBean is the JMX connector, and the JaasLoginServiceRemotingServer GBean is the server wrapper that connects the JMX connector as a server to the JaasLoginService.

As a result of this configuration, Geronimo offers secure JMX access to the JaasLoginService with a server listening on port 4242 using the JMX protocol.

Authorization and JACC

Most of the discussions in this chapter centers around authentication. For authorization, Geronimo fully supports JSR 115, the JACC specification. JAAC represents a set of contracts between authorization policies and the Geronimo server. Implementing the JACC specification means that the container supports three separate subcontracts:

  1. Provider Configuration

  2. Policy Configuration

  3. Policy Decision and Enforcement

This allows the container to apply a standard for authorization to your servlet and EJB applications, using the java.security.Policy object to make these decisions.

One major end result of JACC implementation is the ability to support J2EE standard declarative security elements.

Geronimo, through JACC, supports the ability to handle static principal-to-role mappings from your application’s deploy descriptors/plans. Essentially, this means that your authorization decisions can be implemented through flexible policies based on a deployment descriptor, instead of having proprietary authorization code specifically used within the EJB and/or Web containers.

It allows declarative principal/role mapping access and permission control within your Web and EJB applications. You will see how to declare principal/role mapping later in this chapter.

With most of the theory out of the way, the following sections examine how to configure the components in the Geronimo security architecture.


Configuring JAAS Login Modules

JAAS 1.0 is part of J2SE platform. This section shows how to configure JAAS login module. This configuration can be used by not only by Geronimo but also by other servers or containers (such as JBoss, WebLogic, Tomcat, or Jetty).

J2SE JAAS Login Modules Configuration

Typically, when using the J2SE platform, JAAS login modules are configured in a configuration file, named either login-config.conf or jaas.conf. The configuration entries in this file have the following syntax:

<name used by application to refer to this entry> {
    <LoginModule> <flag> <LoginModule options>;
    <optional additional LoginModules, flags and options>;
    };

For more information on this syntax, see”JAAS Login Configuration File,” at http://java.sun .com/j2se/1.4.2/docs/guide/security/jaas/tutorials/LoginConfigFile.html.

The flag represents the module behavior (Required, Requisite, Sufficient, and Optional), while the set of options is specific to that LoginModule. Following is an example of how this file may look when populated:

MyConfig {
   example.module.MyLoginModule  required debug=true;
};

MySQLConfig {
   Example.module.MyDBLoginModule  required
            connection="jdbc:mysql://localhost:3306/sample";
};

This file is typically specified through the java.security.auth.login.config property when starting the JVM. For example:

java –Djava.security.auth.login.config=c:\\login-config.conf MyContainer

Some application servers will implement configured JAAS login modules through this file, and some will have their own proprietary ways of configuring these entries (such as with an XML file, or through programmatic means).

JBoss uses a login-config.xml file, and BEA Weblogic uses MBeans and MBean Definition Files. Geronimo has its own way to configure login modules. It is done through the configuration of specialized GBeans in deployment plans.

Configuration JAAS Login Modules in Geronimo

In Geronimo, you can configure login modules by first specifying a GeronimoLoginConfiguration GBean in the deployment plan. This GBean will build a JAAS configuration. A typical GeronimoLoginConfiguration entry may look like this:

<gbean name="LoginConfiguration"
class="org.apache.geronimo.security.jaas.GeronimoLoginConfiguration">
        <references name="Configurations">
            <pattern><type>SecurityRealm</type></pattern>
            <pattern><type>ConfigurationEntry</type></pattern>
        </references>
    </gbean>

The GeronimoLoginConfiguration GBean manages each of the JAAS configuration entries. This GBean builds a complete JAAS configuration, and, in fact, extends the javax.security.auth.login .Configuration class, which is the JAAS representation of the login configuration presented in the last section. This GBean’s primary responsibility is to collect and build a JAAS configuration.

During run time, the GeronimoLoginConfiguration GBean looks for other GBeans of certain types that represent the actual configuration entries. In Geronimo, configuration entries are represented by objects that implement the ConfigurationEntryFactory interface.

For example, as shown in the previous configuration segment, GeronimoLoginConfiguration looks for other GBeans that represent the type of SecurityRealm and ConfigurationEntry. These two J2EE component object types usually represent GBeans in the system that implements the ConfigurationEntryFactory interface. The <pattern> element tells Geronimo to match for any objects of type that matches the specified pattern.

GBeans that implement the ConfigurationEntryFactory interface represent the actual configuration entry and minimally will contain the necessary information to produce a JAAS configuration. This includes an application name and a reference to a LoginModule (which usually is yet another GBean).

The ConfigurationEntryFactory is then capable of returning the entire configuration in an object known as a JaasLoginModuleConfiguration. Geronimo offers three different types of GBeans that implement the ConfigurationEntryFactory interface:

  • DirectoryConfigurationEntry

  • ServerRealmConfigurationEntry

  • GenericSecurityRealm

The following sections examine each of these GBeans in turn.

DirectConfigurationEntry

The DirectConfigurationEntry GBean is a configuration entry that allows you to have a direct link to a single LoginModule. Nothing will go through the JaasLoginService GBean to use the Geronimo Login API, nor will a JaasLoginCoordinator be used to proxy the LoginModule’s access. It essentially does what the name of the GBean states - provides a direct link to a configuration with a single LoginModule. It’s a way to create a simple login configuration.

The following plan snippet shows a DirectConfigurationEntry set up with a Derby LoginModule that handles authentication based on a Derby database. The application configuration is called myApplication and sets the LoginModule’s control flag to REQUIRED. It references a LoginModule named DerbyLoginModule. (See the highlighted code in the following listing.)

<gbean name="MyApplicationDirectConfigurationEntry"
      class="org.apache.geronimo.security.jaas.DirectConfigurationEntry">
  <attribute name="applicationConfigName">myApplication</attribute>
  <attribute name="controlFlag">REQUIRED</attribute>
  <reference name="Module">
    <name>DerbyLoginModule</name>
  </reference>
</gbean>

<gbean name="DerbyLoginModule"
      class="org.apache.geronimo.security.jaas.LoginModuleGBean">
    <attribute name="loginModuleClass">
      org.apache.geronimo.security.realm.providers.SQLLoginModule</attribute>
    <attribute name="serverSide">true</attribute>
    <attribute name="options">
      jdbcUser=system
      jdbcPassword=manager
      jdbcURL=jdbc:derby:net://localhost:1527/SystemDatabase;
      jdbcDriver=com.ibm.db2.jcc.DB2Driver
      userSelect=select user, pswd from myapp.users
      groupSelect=select role, user from myapp.userroles
    </attribute>
    <attribute name="loginDomainName">derby-login-realm</attribute>
</gbean>

Don’t worry too much about the LoginModule configuration at this point; it will be discussed in great detail later in the chapter.

The DirectConfigurationEntry GBean allows you to create a simple configuration entry wired to a single LoginModule. Table 15-1 shows the DirectConfigurationEntry GBean’s attributes.

Table 15-1: DirectConfigurationEntry GBean Open table as spreadsheet
Type | Name | Req | Description
A | applicationConfigName | Yes | The name of the configuration entry.
A | controlFlag | Yes | One of the four control flags used for the LoginModule. REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL.
R | Module | Yes | References the name of a LoginModule GBean.
Legend Type: (A) - Attribute, (R) - Reference to GBean Req: (Yes) - parameter is required, (No) - not required

ServerRealmConfigurationEntry

The ServerRealmConfigurationEntry GBean is a special component that allows you to create a new configuration name to be used with an existing, configured security realm (GenericSecurityRealm).

Typically, a GenericSecurityRealm will have the realm name configured as the application configuration name. However, the ServerRealmConfigurationEntry allows you to reuse an already configured security realm and add an application configuration name to the realm. This is essentially an alias to another name to the security realm. The following is a snippet from the Geronimo default security plan that allows the geronimo-properties-realm to be aliased to the name JMX:

<gbean name="JMX"
       class="org.apache.geronimo.security.jaas.ServerRealmConfigurationEntry">
  <attribute name="applicationConfigName">JMX</attribute>
  <attribute name="realmName">geronimo-properties-realm</attribute>
  <reference name="LoginService"><name>JaasLoginService</name></reference>
</gbean>

The reason you may wish to do this is to avoid duplicating a full security realm. A perfectly good use case for this is what is representative of this in the previous example. The Geronimo security configuration needs to allow for JMX remoting of the geronimo-properties-realm, or basically allow another application the ability to reference this realm by the JMX name. This snippet leverages reuse of the geronimo-security-realm and additionally allows the configuration to be referenced with the JMX application configuration name.

Another use case may be that you have several applications that require different names for the security realm, but you may want to have the same security realm implementation. In this case, you simply create an alias (using a ServerRealmConfigurationEntry) for each application.

The ServerRealmConfigurationEntry GBean allows you to attach an application configuration name to an already existing security realm. Table 15-2 shows the ServerRealmConfigurationEntry GBean’s attributes and descriptions.

Table 15-2: ServerRealmConfigurationEntry GBean Open table as spreadsheet
Type | Name | Req | Description
A | applicationConfigName | Yes | The name of the configuration entry.
A | realmName | Yes | Name of an existing security realm.
A | wrapPrincipals | No | May be true or false. Defaults to false. If set to true, all principals will be wrapped with a DomainPrincipal and RealmPrincipal. This is used to help differentiate between the same principal that is added by two different login modules.
R | LoginService | Yes | References the name of the JaasLoginService GBean.
Legend Type: (A) - Attribute, (R) - Reference to GBean Req: (Yes) - parameter is required, (No) - not required

GenericSecurityRealm

The GenericSecurityRealm represents a Geronimo security realm, explored earlier in the section “Security Realms and Login Domains.” Technically, a GenericSecurityRealm GBean implements the SecurityRealm Java interface. Translated, it means that you can use this component to configure a security realm. GenericSecurityRealm allows you to configure login module chaining, enabling authentication policy that utilizes multiple LoginModules.

In Geronimo, a security realm minimally involves three GBeans:

  • GenericSecurityRealm - The main security realm GBean.

  • JaasLoginModuleUse - A wrapper GBean that takes a reference to a LoginModuleGbean, and provides for setting the LoginModule’s control flag and reference additional JaasLoginModuleUse GBeans for LoginModule chaining. Typically, each LoginModuleGbean will have one JaasLoginModuleUse GBean referencing it.

  • LoginModuleGbean - The GBean referenced by the JaasLoginModuleUse GBean. This is a GBean that wraps an actual LoginModule class.

The LoginModuleGBean and JaasLoginModuleUse GBeans will be explained in detail later in this chapter. This section concentrates on the GenericSecurityRealm.

The Listing 15-1 code snippet comes from the default security configuration in Geronimo. This is an example of how the geronimo-properties-realm security realm configuration was configured in the j2ee-security plan.

Important

You can only see this plan by looking at the Geronimo source because it is distributed as a compiled CAR file in the binary distribution.

Listing 15-1: Example Realm Configuration of a geronimo-properties-realm
Image from book
    <gbean name="geronimo-properties-realm"
        class="org.apache.geronimo.security.realm.GenericSecurityRealm">
        <attribute name="realmName">geronimo-properties-realm</attribute>
        <reference name="LoginModuleConfiguration">
             <name>properties-login</name>
       </reference>
        <reference name="ServerInfo"><name>ServerInfo</name></reference>
        <reference name="LoginService"><name>JaasLoginService</name></reference>
    </gbean>

    <gbean name="properties-login"
class="org.apache.geronimo.security.jaas.JaasLoginModuleUse">
         <attribute name="controlFlag">REQUIRED</attribute>
         <reference name="LoginModule">
             <name>properties-login</name>
         </reference>
     </gbean>

<gbean name="properties-login"
        class="org.apache.geronimo.security.jaas.LoginModuleGBean">
        <attribute
name="loginModuleClass">org.apache.geronimo.security.realm.providers.PropertiesFile
LoginModule</attribute>
        <attribute name="serverSide">true</attribute>
        <attribute name="options">
            usersURI=var/security/users.properties
            groupsURI=var/security/groups.properties
        </attribute>
        <attribute name="loginDomainName">geronimo-properties-realm</attribute>
    </gbean>
Image from book

Make note of the geronimo-properties-realm GBean that is of GenericSecurityRealm type. The realmName attribute represents the name of the realm, as well as representing the application configuration name. It’s this name that you would reference in your applications when you want to use this realm. It is important to remember that with a GenericSecurityRealm, the realmName is the JAAS application configuration name.

Also remember from the last section that, if you want to decouple the realm name and the application configuration name (or to create an alias), you can use an additional ServerRealmConfigurationEntry GBean to reference this realm.

The LoginModuleConfiguration reference will refer to the name of the JaasLoginModuleUse GBean, which is a wrapper to the LoginModuleGBean.

Important

In Listing 15-1 , the plan contains GenericSecurityRealm a reference to the LoginService GBean and refers to it in the following manner:

<reference name="LoginService">
    <name>JaasLoginService</name>
</reference>
Improtant

It is important to remember that this reference was only valid when it was in the same plan as the LoginService GBean. When you write your own plans to be deployed in Geronimo, be sure to declare your dependency on the j2ee-security plan so that it can find it, as follows:

<environment>
<dependencies>
   <dependency>
       <groupId>geronimo</groupId>
       <artifactId>j2ee-security</artifactId>
       <type>car</type>
   </dependency>
</dependencies>
</environment>
<reference name="LoginService">
    <name>JaasLoginService</name>
</reference>

Failure to do so will result in a deployment error.

The GenericSecurityRealm GBean allows you to configure a security realm that may be made up of one or more chained LoginModules. Table 15-3 lists the GenericSecurityRealm GBean configuration attributes and references.

Table 15-3: GenericSecurityRealm GBean Open table as spreadsheet
Type | Name | Req | Description
A | realmName | Yes | The name and is also the JAAS application configuration name.
A | defaultPrincipal | No | Represents a default principal to use when the client is unauthenticated. Not normally needed unless you need a principal to be used for when an unauthenticated user needs to access your applications and needs principal representation.
A | restrictPrincipalsToServer | No | true or false. If set to true, clients will not be able to obtain principals generated by this realm from the login service. If false, clients will be able to receive all principals generated by this realm. Default is false.
A | wrapPrincipals | No | May be true or false. Defaults to false. If set to true, all principals will be wrapped with a DomainPrincipal and RealmPrincipal. This is used to make the principals unique so that they do not clash with other LoginModules’ principals that may use the same principal type.
R or X | LoginModuleConfiguration | No | When used as a reference, this will be the name reference to a JaasLoginModuleUse GBean. When used as an XML reference, will contain the XML to configure a full LoginModule based on the login-config schema. Although configuring a LoginModule is not necessary, it is recommended, since the security will be useless without one.
R | ServerInfo | Yes | Name reference to the ServerInfo GBean.
R | LoginService | Yes | Name reference to the JaasLoginService GBean.
Legend Type: (A) - Attribute, (R) - Reference to GBean, (X) - Contains an XML configuration Req: (Yes) - parameter is required, (No) - not required

Login Modules

LoginModules are configured with the LoginModuleGBean. This GBean is a wrapper for the actual JAAS login module itself. Configuration attributes include which LoginModule class to use, as well as the options that are to be set. Refer to the section “J2SE JAAS Login Modules Configuration” earlier in this chapter to see the corresponding login module configuration attributes.

The following is an example LoginModuleGBean configuration that sets up org.apache.geronimo .security.realm.providers.LDAPLoginModule, which is one of Geronimo’s included LoginModules in the ldap-demo example included with the Geronimo source code:

<gbean name="ldap-login"
        class="org.apache.geronimo.security.jaas.LoginModuleGBean">
        <attribute
name="loginModuleClass">org.apache.geronimo.security.realm.providers.LDAPLoginModul
e</attribute>
        <attribute name="serverSide">true</attribute>
        <attribute name="options">
          initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
          connectionURL=ldap://localhost:1389
          connectionUsername=uid=admin,ou=system
          connectionPassword=secret
          connectionProtocol=
          authentication=simple
          userBase=ou=users,ou=system
        userSearchMatching=uid={0}
        userSearchSubtree=false
        roleBase=ou=groups,ou=system
        roleName=cn
        roleSearchMatching=(uniqueMember={0})
        roleSearchSubtree=false
        userRoleName=
     </attribute>
  <attribute name="loginDomainName">ldap-realm</attribute>
</gbean>

Notice the loginModuleClass attribute references the LoginModule’s LDAP class, and the options are each listed on a different line in the options attribute. The serverSide attribute is a flag that states that all of the processing will occur on the server. This means that the client will be authenticated through the server and that the server will process the authentication. It is highly recommended that you leave this parameter as true, since a majority of the time you will have the server process the authentication.

The LoginModuleGBean GBean represents a LoginModule configuration. Table 15-4 describes the LoginModuleGBean attributes.

Table 15-4: LoginModuleGBean GBean Open table as spreadsheet
Type | Name | Req | Description
A | loginModuleClass | Yes | The name of the actual LoginModule class.
A | serverSide | Yes | May be true or false. Should be set to true. If true, it handles all of the authentication on the server side.
A | options | No | Sets options that are specific to the login module. Each option should be on its own line within the attribute.
A | wrapPrincipals | No | May be true or false. Defaults to false. If set to true, all principals will be wrapped with a DomainPrincipal and RealmPrincipal. This is used to make the principals unique so that they do not clash with other LoginModules’ principals that may use the same principal type.
A | loginDomainName | Yes | Unique name for the LoginModule. Usually a good idea to name it after the login domain, such as mysql-realm.
Legend Type: (A) - Attribute, (R) - Reference to GBean Req: (Yes) - parameter is required, (No) - not required

At this point, you are probably looking at the LoginModuleGBean and the login configuration and are wondering about a key missing component. The control flag in this GBean is configured in other GBeans. The reason is that the LoginModules are meant be reusable. You may have more than one security realm or configuration use a LoginModule, yet the control flags can change based on the realm. One realm may have a requirement (REQUIRE) that the LoginModule succeed, where another realm may make this optional (OPTIONAL).

When using a DirectConfigurationEntry GBean, you can set the control flag for the LoginModule in its controlFlag attribute. The ServerRealmConfigurationEntry does not have one, since it just allows the ability to rename the configuration. But the GenericSecurityRealm configuration refers to a special type of GBean, called a JaasLoginModuleUse, which allows you to set the controlFlag attribute for the LoginModule. The GenericSecurityRealm does not ever directly refer to a LoginModule, but uses JaasLoginModuleUse the instead.

JaasLoginModuleUse GBean

The JaasLoginModuleUse GBean is a wrapper for the LoginModuleGBean, which has a special function. Not only does it add an abstraction to be able to reuse a LoginModule (so that the controlFlag can be changed for different security realms), but it also allows you to configure LoginModule chaining. This means that your security realm can have the ability to use multiple LoginModules as part of a single configuration.

An example that was used earlier that could apply here is a single sign-on, where your realm will need to access an NTLM authentication, then also have it pass an LDAP authentication. To do this, these LoginModules would need to be chained. In this example, the NTLM GBean would be first, then chained to the LDAP GBean. The following snippet shows how this type of configuration would look:

<gbean name="ntlm-login"
     class="org.apache.geronimo.security.jaas.Jaas LoginModuleUse">
  <attribute name="controlFlag">REQUIRED</attribute>
  <reference name=" LoginModule">
    <name>ntlm-login</name>
  </reference>
  <reference name="Next">
    <name>ldap-login</name>
  </reference>
</gbean>

<gbean name="ldap-login"
     class="org.apache.geronimo.security.jaas.Jaas LoginModuleUse">
  <attribute name="controlFlag">REQUIRED</attribute>
  <reference name=" LoginModule">
    <name>ldap-login</name>
  </reference>
</gbean>

The actual LoginModuleGBean configurations are not shown here for brevity, just the JaasLoginModuleUse GBeans. Notice how the Next reference for the ntlm-login JaasLoginModuleUse GBean refers to the ldap-login, making a chain. The fact that the ldap-login JaasLoginModuleUse GBean does not have a Next reference means it is the end of the chain.

The JaasLoginModuleUse GBean allows you to chain LoginModules when used with a GenericSecurityRealm configuration entry. Table 15-5 describes this GBean’s attributes.

Table 15-5: JaasLoginModuleUse GBean Open table as spreadsheet
Type | Name | Req | Description
A | controlFlag | Yes | One of the four control flags used for the LoginModule. REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL
R | LoginModule | Yes | Named reference to the name of a LoginModuleGBean GBean
R | Next | No | Named reference of another JaasLoginModuleUse GBean that represents the next LoginModule in the chain
Legend Type: (A) - Attribute, (R) - Reference to GBean Req: (Yes) - parameter is required, (No) - not required

Included Login Modules

LoginModules can authenticate to many login domains, including LDAP, a database, a flat file, certificates, and so on. Luckily, you do not need to write LoginModules to enable these capabilities. Geronimo comes with a set of LoginModules that should fit most of your authentication needs. The full suite of Geronimo LoginModules are found in the org.apache.geronimo.security.realm.providers package:

  • PropertiesFileLoginModule

  • SQLLoginModule

  • LDAPLoginModule

  • CertificateChainLoginModule

  • CertificatePropertiesFileLoginModule

Geronimo also includes login modules that do not even have anything to do with authentication but act as a utility when used with other LoginModules in a chain with a GenericSecurityRealm. These types of modules act as utilities and can do things such as audit logging of security or lock out a user after a certain number of failed attempts, or even gather passwords and credentials to be accessed by other parts of the application. These utility LoginModules include the following:

  • FileAuditLoginModule

  • GeronimoPasswordCredentialLoginModule

  • RepeatedFailureLockoutLoginModule

Table 15-6 lists all of the included LoginModules that come with Geronimo, as well as a description of their configuration options.

Table 15-6: Geronimo-Included LoginModules Open table as spreadsheet
LoginModule | Description | Option | Req | Description
PropertiesFileLogin Module | LoginModule that uses user and group property files for a domain. | usersURI | Yes | The URI to a properties file that consists of user/password name/ value pairs in the format of user=password.
 |  | groupsURI | Yes | The URI to a properties file that consists of group/users name/value pairs in the format of group=user1,user2,user3, … where each group is followed by the user list that belongs in that group. Each user is delimited by a comma.
SQLLoginModule | LoginModule that allows you to authenticate against a database domain. | jdbcDriver | No | Class driver used. Only needed if not using a dataSourceName.
 |  | jdbcURL | No | JDBC Database connection URL. Only needed if not using a dataSourceName.
 |  | jdbcUser | No | The user to be used to login to the database. Only needed if not using a dataSourceName.
 |  | jdbcPassword | No | The password to be used to login to the database. Only needed if not using a dataSourceName.
 |  | dataSourceName | No | The name of a configured data-source to use as the basis of the connection parameters. This is the recommended way to use this LoginModule so that it can leverage database pools. Using this parameter will ignore the JDBC parameters if set.
 |  | dataSource Application | No | Only used if the dataSourceName is set. The configurationId of the application module for which the dataSourceName was configured. Do not include or set to null for a systemwide configuration.
 |  | userSelect | Yes | A SQL select statement, that returns the username and pass-word, in that order, and should include a (?) parameter in the where clause that does a lookup of the username. Example: select username, password from users where username = ?
 |  | groupSelect | Yes | A SQL select statement, that returns the username and group, in that order, and should include a (?) parameter in the where clause that does a look up of the username. Example: select user, group from groups where username = ?
LDAPLoginModule | LoginModule that authenticates against a LDAP domain. | initialContext Factory | Yes | The InitialContext factory to use. Usually should be com.sun .jndi.ldap.LdapCtxFactory.
 |  | connectionURL | Yes | URL of the LDAP server to connect to. For a production LDAP this will be ldap://[your server’s LDAP host address]:389.
 |  | connection Username | Yes | The distinguished name (DN) of the user to bind. Should be administrator or directory manager that has access to examine passwords.
 |  | connection Password | Yes | Password of user to bind.
 |  | connection Protocol | Yes | String that determines the security protocol, such as SSL. Valid options are up to the service provider. An empty setting such as connectionProtocol= is an acceptable entry.
 |  | authentication | Yes | Usually one of several protocols. Typically will be “none”, “simple”, or “strong”.
 |  | userBase | Yes | Base of the LDAP search string for the users.
 |  | userSearch Matching | Yes | The LDAP attribute search string to find the user. Use {0} as your substitution parameter. Example: uid={0}
 |  | userSearch Subtree | Yes | true or false. If true, the search will encompass the entire subtree. If false, it will only be at the level of the search.
 |  | roleBase | Yes | LDAP string specifying the base objects from which to search for group/role.
 |  | roleName | Yes | Attribute name that references the role name.
 |  | roleSearch Matching | Yes | The LDAP search string to find the user. The value here depends on how your group schema is configured. Generally, the role will have many attributes that are the same, but with different values. An example is memberUID for LDAP authentication for UNIX systems. In this scenario, the value of the roleSearchMatching would be (memberUID={0}).
 |  | roleSearch Subtree | Yes | Base of the LDAP search string for the roles.
 |  | userRoleName | Yes | This attribute should list the name of the roles LDAP attribute if the roles information is carried in the user schema. Typically, the user information is set within the memberUID of the roles schema. However, to support the roles listed in a user schema, where this schema contains something like a memberOf attribute, it lists those roles. An empty setting such as userRoleName= is an acceptable entry. An empty setting means it is not used and is mutually exclusive of the roleSearchMatching.
CertificateProperties FileLoginModule | Reads a list of groups and users form properties files and checks that there is an SSL certificate that matches the user. The authentication is actually handled by the SSl layer to verify user ID and password. If a principal is delivered via the certificate, it is accepted and the group is handled via a lookup from the property file. | usersURI | Yes | The URI to a properties file that consists of a user list of valid users in the format of each user on each line.
 |  | groupsURI | Yes | The URI to a properties file that consists of group/users name/value pairs in the format of group=user1,user2,user3,… where each group is followed by the user list that belongs in that group. Each user is delimited by a comma.
CertificateChainLogin Module | Authenticates users against a chain of certificates, validating that the certificate(s) has(have) a principal. This is usually used in server-to-server communication, where one server may present a chain of certificates to although it could be used for a Web client as well. This LoginModule does not do any actual authentication, but instead assumes that the certificate chain is acceptable, since it has already been used to construct a clientcertificate-authenticated SSL connection. It simply extracts the principal from the first certificate-distinguished name and additionally wraps it in a GeronimoUserPrincipal so getUserPrincipal() can work correctly. |  |  |
FileAuditLoginModule | Writes authentication requests and attempts to write to an audit file. This module is not for authentication but is instead used in a LoginModule chain after another LoginModule that is responsible for the actual login. Since this must be used in a chain, it must be used with a GenericSecurityRealm configuration entry. To use, the primary LoginModule’s control flag should be set to REQUIRED or OPTIONAL, while the control flag for this module can be set to any of the settings. | file | Yes | The URI of the log file to create and use. Relative paths are relative to $GERONIMO_HOME. Example: var/log/securityautit.log
GeronimoPassword CredentialLoginModule | Allows you to keep track of a user’s credentials or password and is stuffed as a GeronimoPasswordCredential object in the subject’s private creden- tial set if the login is successful. This allows your applications the ability to retrieve the paswords when they would normally be lost after authen- tication. This module is not for authentication but is instead used in a LoginModule chain after another LoginModule that is responsible for the actual login. Since this must be used in a bchain, it must e used with a GenericSecurityRealm configuration entry. To use, the primary LoginModule’s control flag should be set to REQUIRED or OPTIONAL, while the control flag for this module should be set to REQUISITE. |  |  |
RepeatedFailure LockoutLoginModule | Tracks and controls a user’s num- ber of failures within a period of time and can lock that user out from logging in for a specified length of time. This module is not for authentication, but is instead used in a LoginModule chain after another LoginModule that is responsible for the actual login. Since this must be used in a chain, it must be used with a GenericSecurityRealm con- figuration entry. To use, the primary LoginModule’s control flag, should be set to REQUIRED or OPTIONAL, while the control flag for this module should be set to REQUISITE. | failureCount | No | Number of failures allowed within the periods of time. Defaults to 5.
 |  | failurePeriod Secs | No | Failure period in seconds. Represents the time period win- dow for which failures can occur. Defaults to 300 seconds, or 5 minutes.
 |  | lockout DurationSecs | No | Amount of time in seconds that the user will be locked out based upon exceeding the failureCount. Defaults to 1800 seconds, or 30 minutes.

Simplifying LoginModule Configuration with the xml-reference login-config

You should notice that wiring a GenericSecurityRealm and a LoginModule took a minimum of three GBeans. Once you begin chaining LoginModules, the number of GBeans will escalate by two for each LoginModule in to your realm. This will also include editing your JaasLoginModuleUse GBeans to add the next attribute to point to your newly chained LoginModule. It can quickly get unwieldy, and there is a much simpler way to wire up a GenericSecurityRealm configuration with a LoginModule by using the xml-reference login configuration.

The xml-reference login configuration allows you to embed an XML login module configuration inside the GenericSecurityRealm GBean. This configuration can have as many login modules as you want as a part of your chain, and this will all involve setting up only a single GBean.

How this works is the LoginModuleConfiguration reference in the GenericSecurityRealm GBean will take two types of references: a reference to a JaasLoginModuleUse GBean, or an xml-reference configuration. If the LoginModuleConfiguration is tagged as an xml-reference, then it will contain a login-config xml login-config.

Listing 15-2 shows a GenericSecurityRealm GBean configuration that it set up to use the xml-reference for the LoginModuleConfiguration, and contains two LoginModules: PropertiesFileLoginModule and FileAuditLoginModule.

Listing 15-2: Example Realm Configuration Using an xml-reference
Image from book
<environment>
<dependencies>
      <dependency>
       <groupId>Geronimo</groupId>
       <artifactId>j2ee-security</artifactId>
       <type>car</type>
      </dependency>
</dependencies>
</environment>

...

<gbean name="one-gbean-properties-realm"
         class="org.apache.geronimo.security.realm.GenericSecurityRealm">
    <attribute name="realmName">one-gbean-properties-realm</attribute>
    <xml-reference name="LoginModuleConfiguration">
    <lc:login-config xmlns:lc="http://geronimo.apache.org/xml/ns/loginconfig">
      <lc:login-module control-flag="REQUIRED" server-side="true">
        <lc:login-domain-name>one-gbean-properties-realm</lc:login-domain-name>
        <lc:login-module-class>
org.apache.geronimo.security.realm.providers.PropertiesFileLoginModule</lc:login-
module-class>
        <lc:option name="usersURI">var/security/users.properties</lc:option>
        <lc:option name="groupsURI">var/security/groups.properties</lc:option>
      </lc:login-module>
      <lc:login-module control-flag="REQUISITE" server-side="true">
           <lc:login-domain-name>one-gbean-properties-realm</lc:login-domain-name>
        <lc:login-module-class>
org.apache.geronimo.security.realm.providers.FileAuditLoginModule</lc:login-module-
class>
        <lc:option name="file">var/log/securityaudit.log</lc:option>
      </lc:login-module>
    </lc:login-config>
    </xml-reference>
    <reference name="ServerInfo">
      <name>ServerInfo</name>
     </reference>
    <reference name="LoginService">
       <name>JaasLoginService</name>
    </reference>
  </gbean>
Image from book

Notice that once the LoginModuleConfiguration is set to use the xml-reference, a login-config is a child of the xml-reference. The <login-config> element must start the configuration with a name space declaration to the loginconfig schema, or xmlns:lc="http://geronimo.apache.org/xml/ ns/loginconfig". In this example, lc is designated as the domain prefix for the rest of the configuration. This name space declaration is important, since it will help the deployer validate that your configuration is syntactically correct.

Login-config Tag

Inside the element, you can add one or more login modules. There are two ways to refer to a login module here. You can refer to another LoginModule by referring to it by its GBean reference (which allows you to reuse already configured LoginModules), or you can fully declare a LoginModule in its entirety.

...
<lc:login-config xmlns:lc="http://geronimo.apache.org/xml/ns/loginconfig">
  <lc:login-module-ref>
    ...
  </lc:login-module-ref>
  <lc:login-module>
    ...
  </lc:login-module>
</lc:login-config>
...

To refer to a login that has already been created, you use the <login-module-ref> element. To declare a new LoginModule, you use the <login-module> element.

Login-module-ref Element

The <login-module-ref> element is used to refer to another LoginModule that has already been declared. First, the element requires the control-flag attribute, which may contain one of the four control flags used for the LoginModule reference, REQUIRED, REQUISITE, SUFFICIENT, or OPTIONAL. The element must also contain a child <name> attribute that contains the named reference. It may also optionally consist of a number of additional elements that will help the deployer find the LoginModule. The following are a list of these elements:

  • <domain> - The GBean domain component of the name. In a standard configuration, this would be (and should be) geronimo.server. This is an optional element, and it will default to the JSR-77 naming convention if it is not used. The default will typically be geronimo.server.

  • <server> - The server component of the GBean name. In a standard configuration, this would be (and should be) geronimo. This is an optional element and it will default to the JSR-77 naming convention if it is not used. The default will typically be geronimo.

  • <application> - The application component of the GBean name. It should usually reference the applicationId of an application module or configId if the applicationId is not used. If neither are used, then it should be null. This is an optional element, and it will default to null if it is not used.

  • <module> - The module that the LoginModule resides. This will reference the configId of the module containing the LoginModule. This is an optional element, and it will default to the current plan’s configId if not used.

  • <type> - Should be set to LoginModule since it will be referencing a LoginModule type. This is an optional element, and it will default to LoginModule if not used.

An example <login-module-ref> declaration would look like the following:

...
<lc:login-module-ref control-flag="REQUIRED">
  <lc:domain>geronimo.server</lc:domain>
  <lc:server>geronimo</lc:server>
  <lc:application>null</lc:application>
  <lc:module>geronimo/j2ee-security/1.0/car</lc:module>
  <lc:type>LoginModule</lc:type>
  <lc:name>properties-login</lc:name>
</lc:login-module-ref>
...

Login-module Element

The other way to declare a LoginModule with the login-config XML is with the <login-module> element. This allows you to fully configure and declare a LoginModule with all of the trimmings. Like the <login-module-ref> element, this also requires the control-flag attribute, but it also has the server- side attribute as well. This attribute means that the client will be authenticated through the server and that the server will process the authentication. It is highly recommended to set this parameter as true, since a majority of the time you will have the server process the authentication. The <login-module> element also has several child elements that match the standard GBean LoginModule configuration:

  • <login-domain-name> - Unique name for the LoginModule. Usually it is a good idea to name it after the login domain, such as mysql-realm. This is a required element.

  • <login-module-class> - The name of the actual LoginModule class. The full package name and class are required. An example is org.apache.geronimo.security.realm.providers .PropertiesFileLoginModule. This is a required element.

  • <option name="Option Name"> - If your LoginModule has options for the class being used, you may have one or more options that need to be set. This element must use the name attribute for the name of the option, and the value will be in the body of the element. The requirement of this element is dependent on the LoginModule class that is used.

The following is an example <login-module> declaration using a PropertiesFileLoginModule:

...
<lc:login-module control-flag="REQUIRED" server-side="true">
  <lc:login-domain-name>one-gbean-properties-realm</lc:login-domain-name>
  <lc:login-module-class>
    org.apache.geronimo.security.realm.providers.PropertiesFileLoginModule
  </lc:login-module-class>
  <lc:option name="usersURI">var/security/users.properties</lc:option>
  <lc:option name="groupsURI">var/security/groups.properties</lc:option>
</lc:login-module>
...

For those who prefer to view XML schemas, Listing 15-3 is the full XML schema for the embeddable login-config xml configuration. As you can see, configuring a GenericSecurityRealm with the xml-reference for LoginModules is much simpler, since you can clearly see and maintain the realm configuration in a single GBean.

Listing 15-3: Login-config XML Schema
Image from book
<xsd:schema
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:j2ee="http://java.sun.com/xml/ns/j2ee"
    xmlns:geronimo="http://geronimo.apache.org/xml/ns/loginconfig-1.1"
    targetNamespace="http://geronimo.apache.org/xml/ns/loginconfig-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"
    elementFormDefault="qualified"
    attributeFormDefault="unqualified"
    version="1.0">
    <xsd:import namespace="http://geronimo.apache.org/xml/ns/deployment-1.1"
schemaLocation="geronimo-config-1.1.xsd"/>
     <xsd:element name="login-config" type="geronimo:login-configType"/>

    <xsd:complexType name="login-configType">
    <xsd:annotation>
      <xsd:documentation>
        Defines the list of login modules for a login configuration
        represented by a GenericSecurityRealm
      </xsd:documentation>
    </xsd:annotation>
    <xsd:sequence>
      <xsd:choice minOccurs="0" maxOccurs="unbounded">
        <xsd:element name="login-module-ref" type="geronimo:login-module-refType"
                 minOccurs="0" maxOccurs="unbounded"/>
        <xsd:element name="login-module" type="geronimo:login-moduleType"
                 minOccurs="0" maxOccurs="unbounded"/>
      </xsd:choice>
    </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="abstract-login-moduleType" abstract="true">
    <xsd:attribute name="control-flag" type="geronimo:control-flagType"
                  use="required"/>
    </xsd:complexType>

    <xsd:complexType name="login-module-refType">
      <xsd:complexContent>
        <xsd:extension base="geronimo:abstract-login-moduleType">
          <xsd:sequence>
            <xsd:element name="domain" type="xsd:string" minOccurs="0"/>
            <xsd:element name="server" type="xsd:string" minOccurs="0"/>
            <xsd:element name="application" type="xsd:string" minOccurs="0"/>
            <xsd:element name="module" type="xsd:string" minOccurs="0"/>
            <xsd:element name="type" type="xsd:string" minOccurs="0"/>
            <xsd:element name="name" type="xsd:string"/>
        </xsd:sequence>
       </xsd:extension>
    </xsd:complexContent>
    </xsd:complexType>

    <xsd:simpleType name="control-flagType">
      <xsd:restriction base="xsd:string">
        <xsd:enumeration value="REQUIRED"/>
        <xsd:enumeration value="REQUISITE"/>
        <xsd:enumeration value="SUFFICIENT"/>
        <xsd:enumeration value="OPTIONAL"/>
      </xsd:restriction>
    </xsd:simpleType>

   <xsd:complexType name="login-moduleType">
      <xsd:complexContent>
        <xsd:extension base="geronimo:abstract-login-moduleType">
          <xsd:sequence>
            <xsd:element name="login-domain-name" type="xsd:string"/>
            <xsd:element name="login-module-class" type="xsd:string"/>
            <xsd:element name="option" type="geronimo:optionType" minOccurs="0"
                          maxOccurs="unbounded"/>
          </xsd:sequence>
        <xsd:attribute name="server-side" type="xsd:boolean" use="required"/>
      </xsd:extension>
     </xsd:complexContent>
   </xsd:complexType>

    <xsd:complexType name="optionType">
      <xsd:simpleContent>
        <xsd:extension base="xsd:string">
          <xsd:attribute name="name" type="xsd:string" use="required"/>
        </xsd:extension>
      </xsd:simpleContent>
    </xsd:complexType>
</xsd:schema>
Image from book

Configuring Your Realm - The Really Easy Way

Now that you have seen two different ways to manually configure your security realm, you will see how the Geronimo Web console makes security realm configuration a snap. As usual, to access the Web console, you navigate your Web browser to http://localhost:8080/console. (If you are not running Geronimo on the same computer as your Web browser, replace localhost with whatever server name or IP address that Geronimo is running on.) When navigating to the console, you will be asked to log in as the administrator. The username is system and the password is manager (for a standard Geronimo configuration). After successfully logging in, the menus will be on the left side of the console. Select the Security Realms link, and you should see a screen that shows a list of all the configured security realms in Geronimo, as shown in Figure 15-4.

Image from book
Figure 15-4: The Geronimo console’s Security Realms portlet

This Security Realms portlet allows you to add and edit security realms, all from the comfort of your own browser. This portlet additionally will show you usage examples, and it will come up with a final plan for you that you can deploy from your browser or cut and paste into your own plan.

To see how this works, let’s create a new Properties File Realm from the console and name it my-new- realm. On the Securty Realms portlet, select the “Add new security realm link.” This begins the Create Security Realm Wizard that steps you through the realm-creation process. The portlet will show the Step 1, which asks you for the name of your security realm and what type of realm you want to configure. The Portlet Wizard offers you five different types of realms that you can configure, which should support most of your needs.

From the console, you can select a Certificate Properties File Realm, Database (SQL) Realm, LDAP Realm, Properties File Realm, or Other. You can probably figure out which realms match which LoginModules that are included with Geronimo by their name. The Other type of realm is included so that you can configure LoginModules that you may have developed or included yourself. For this example, type in my-new-realm for the name of the security realm and select Properties File Realm from the Realm Type drop-down list, as shown in Figure 15-5.

Image from book
Figure 15-5: Security Realm portlet Step 1

After entering the information, click the Next button and the wizard will take you to Step 2, Configure Login Module. Each Realm type (Properties, Certificate, LDAP, Database, and so on) has a different page for configuration. In this example, you should now be shown the page that shows the options for the Properties File Realm. From the section “Included Login Modules” earlier in this chapter, you can find out that for Properties File Realms, you have a usersURI and groupsURI options. You will set these options pointed to a users.properties and a groups.properties file, respectively.

The Step 2 screen shows you just that. It is requesting a Users File URI and a Groups File URI. Geronimo comes with a users.properties and groups.properties file already configured. (This is how you logged into the console to begin with, using these files for security.) So, you can reuse these. Type var/security/users.properties for the Users File URI and var/security/groups.properties for the Groups File URI, as shown in Figure 15-6.

Image from book
Figure 15-6: Security Realm portlet Step 2

Click the Next button, which will bring you to Step 3, Advanced Configuration. When you saw the list of realm types to choose from, you probably noticed that it was missing several realms that come with Geronimo. In particular, you may have noticed that the utility LoginModules, such as the FileAudit LoginModule, the GeronimoPasswordCredentialLoginModule, and RepeatedFailureLockout LoginModule realm type equivalents, seemed to be missing. Step 3 allows you to set up these Login Modules in the chain.

The form on this portlet page is very simple. It offers you the ability to Enable Auditing, Enable Lockout, and Store Passwords. Of course, these correspond to the chained FileAuditLoginModule, Geronimo PasswordCredentialLoginModule, and RepeatedFailureLockoutLoginModule, respectively. You can select which one of the features you want to use, click its associated checkbox. When you enable the option, it will show additional information that it may need to complete the request. For this example, enable the Auditing and Lockout options. When you enable the Auditing, it will ask you for a log filename. Type var/log/securityaudit.log in the Log File field. When you enable the Lockout option, it will request three additional fields. Enter 3 in the failures field, 300 in the first “seconds” field, and 1800 in the last “seconds” field, as shown in Figure 15-7.

Image from book
Figure 15-7: Security Realm portlet Step 3

At this point, you have three options for what you can do with your realm configuration. You can test a login, skip the test and directly deploy your new realm, or skip the test and just show the plan. These three options are shown as buttons at the bottom of the screen. In this example, you will try out your login to verify that it works. Press the Test a Login button, and you will be shown Step 4, Test Login.

This screen requests for a username and password to try out the authentication. The username and password should be ones that you know are already configured. If you created a Database SQL Realm, you would type in the username and passwords that are set up in your configured tables. In this example, since you are using the properties files that are included with Geronimo (users.properties and groups.properties), you know that a valid username is system and password is manager. Type these values into their respective fields and press the Next button, as shown in Figure 15-8.

Image from book
Figure 15-8: Security Realm portlet Step 4

If you typed in everything correctly, you should see the screen as shown in Figure 15-9. It will tell you if you have succeeded, as well as the principals that it obtained during the authentication.

Image from book
Figure 15-9: Security Realm portlet Step 5

At this point, you have the ability to test again, edit the realm, show the plan, or deploy the realm. Use the Test Again option if you want to try out different usernames and passwords. If you have problems with the authentication, or wish to make changed to the realm, you can select the Edit Realm option. To immediately deploy the new realm, you can select the Show Plan button.

In this example, press the Show Plan button, so that you may view the newly created realm’s plan. This will bring you to the portlet view as shown in Figure 15-10. This screen is one of the most helpful features of this tool. This portlet view lists how the configured realm would look if you had created a security realm plan. It actually creates the plan for you. You can copy and paste the new plan in its own file and follow the instructions on how to deploy this new plan. It also tells you how you can include the new plan within a geronimo-application.xml file that you can distribute with an EAR file.

Image from book
Figure 15-10: Security Realm-Show Deployment Plan screen

You may be wondering why not just deploy the realm from this screen. There are several good reasons for this. You may wish to build an EAR file that you will distribute to multiple servers, for example in a cluster of Geronimo instances. You also may wish to keep a copy of the plan under source control to be a part of a distribution, such as the examples that come with Geronimo. In fact, it is recommended that you use this tool to produce the plan that you can copy/paste to a file when you develop production-level projects, so that you can keep an audit trail of changes that you make. However, you may deploy your realm directly from the console if you wish. On this screen, you have the option of pressing the Edit Settings button (which will bring you to a page that allows you to edit the realm) or pressing Deploy Realm (which will deploy and activate your new realm).

Editing the settings gives you some additional control over the settings of your login modules (such as the control flags and other attributes that were discussed in this chapter). You can always go back to the top-level Security Realm portlet and edit your settings from there with the Edit link next to your realm. Another very powerful tool you can use after you configure your realm is the Usage link, which is also next to your realm on the top-level Security Realms portlet. This link brings you to a screen that gives you some helpful hints on how to use your new realm in a Web application’s web.xml and geronimo- web.xml plans. It will even use your new realm as an example. It’s a great starting point to using your new realm in your applications.

As you can see, configuring your security realms through the Geronimo Web console can be a lot simpler than hand-coding the GBean configuration yourself. At the very minimum, it can be used as a starting point and generate security realm plan for you.

Deployment and the Server Security Plan

Up until now, a lot of ground was covered on the creation of security realms and the configuration of login modules. Outside of the console’s ability to deploy the security realm using a generated plan, there has not been any discussion on how to add realms to your own plans or how to manually deploy a realm from the command line. The rest of this chapter shows how the security realms you create can be used in deployment plans to secure your applications.

Typically, you will either have your security realm configuration in its own plan or include it within a geronimo-application.xml file. If it is in its own plan file, you need a <configuration> element that declares the deployment namespace as follows:

<configuration
       xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1">
...
   <!"GBean security realm goes here -->
...
</configuration>

Embedding it within a geronimo-application.xml is similar. But in this instance, you use the <application> element and a reference to the application namespace.

<application
      xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1"
      >
...
   <!"GBean security realm goes here -->
...
</application>

Deploying a realm from a standalone plan will make your realm available to any resources or application that wishes to use it, and, therefore, is known as a serverwide deployment. If it’s within a geronimo- application.xml file, it is then the realm will only have visibility within the application itself.

Deploying your plan is the same as any other plan deployment in Geronimo. You can use the deploy.sh (or deploy.bat if on Windows) script to deploy, or use the raw Java command. The deploy.sh script is in the $GERONIMO_HOME/bin directory. To deploy a standalone plan file called myrealm.xml, using the deploy.sh script, execute the following command:

deploy.sh –username system –password manager deploy myrealm.xml

To deploy using the Java command, execute the following command:

java -jar bin/deployer.jar deploy myrealm.xml


Using Security in Applications

So far, all of our security discussion has been on details that are specific to the Geronimo server. This is only half of the security equation. The other half is how to use the security realm within your applications. Your applications need the ability to leverage your server-side security so that it can control access to your application resources. This is done with a combination of different descriptor files, depending on the type of components you are deploying.

Web Security

Protecting your Web applications is a mix of editing your web.xml file as well as your geronimo- web.xml plan file with the proper configuration. The web.xml will require one or more <security- constraint> declaration protecting specific URL patterns. It will require a <login-config> section to provide for the actual login and error pages. It will also require one or more <security-role> blocks that declare the roles that will access the Web application. Assuming that you have set up a security realm called my-new-realm, as was done in the last section, an example web.xml might look like the following:

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

    <!--servlets and mappings and normal web.xml stuff here -->

    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Protected</web-resource-name>
            <url-pattern>/protected/*</url-pattern>
            <http-method>GET</http-method>
            <http-method>POST</http-method>
        </web-resource-collection>
        <auth-constraint>
            <role-name>superuser</role-name>
        </auth-constraint>
    </security-constraint>
    <login-config>
        <auth-method>FORM</auth-method>
        <realm-name>This is not used for FORM login</realm-name>
        <form-login-config>
            <form-login-page>/login.jsp</form-login-page>
            <form-error-page>/loginerror.jsp</form-error-page>
      </form-login-config>
    </login-config>
    <security-role>
        <role-name>superuser</role-name>
    </security-role>
</web-app>

In this example, the security constraints are set up so that any URL containing /protected must require the superuser role to access the URL. This handles the web.xml component. The geronimo-web.xml plan minimally just requires a <security-realm-name> element that references the name of the security realm, which in this case is my-new-realm. This will enable full JAAS authentication and authorization. If you are to do this, the role that is referenced in the web.xml must match the roles in your LoginModule’s groups. Therefore, in this example, if you strictly wanted to use JAAS, then all references to <role-name> elements in the web.xml would need to contain admin, since that is the role specified in the groups.properties file. But you will notice that here, the file does not contain admin; it contains superuser.

This is where the security descriptor block is used to leverage the Geronimo JACC support to enable principal/role mapping to form a more sophisticated security arrangement. The principal/role mapping will allow you to create declarative role hierarchies based on user and JAAS role membership. The security descriptor will set up a default principal for those users who do not fit in a particular declared role, and set up the specific declared principal/role mappings. The geronimo-web.xml plan for this example may look as follows:

<?xml version="1.0" encoding="UTF-8"?>
<web-app
    xmlns="http://geronimo.apache.org/xml/ns/web"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming"
    >

    <context-root>/SecureWebApp </context-root>
    <context-priority-classloader>false</context-priority-classloader>

    <security-realm-name>my-new-realm</security-realm-name>

    <!-- BEGIN SECURITY DESCRIPTOR -->
    <security>
        <default-principal>
            <principal name="anonymous"
class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
            />
        </default-principal>
        <role-mappings>
            <role role-name="superuser">
               <principal name="admin" designated-run-as="true"
class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"
               />
               <principal name="system"
class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
               />
            </role>
        </role-mappings>
    </security>
    <!-- END SECURITY DESCRIPTOR -->

</web-app>

In the security descriptor in this plan file, a principal named anonymous is declared and set as the default-principal. By doing this, any user who does not fit within any defined role will be viewed as this anonymous user and be referenced with the anonymous principal. The <role-mappings> section is the tie between the web.xml and this plan file. This is where the role referenced in the web.xml <security-role> matches up with the plan file.

In this example, the role admin is made up of two different kinds of principals: anyone who is in the admin group, and the system user. Therefore, if someone is in the admin group or is the system user, they will fall into the superuser role and will have access to the /protected URLs. If the client is does not fall into this category, then the user carries the anonymous principal and is not granted access to the /protected URLs. The designated-run-as attribute means that if a servlet in the web.xml had the <run-as> element declared with the superuser role, it will use the admin principal.

Important

Other than a geronimo-web.xml file for a WAR archive, the <web-app> element may appear as a module inside of a geronimo-application.xml that is deployed with an EAR.

EJB Security

EJB security is very similar to the Web configuration. However, instead of a web.xml and geronimo-web.xml file, EJBs will use the ejb-jar.xml file and the geronimo-application.xml file. First, it’s important to note that the EJB container’s access will not require declaring the <security- realm-name> as was done for the Web, since at the point of the EJB using the credentials, the authentication would have already occurred. Authentication would have been handled by a Web interface or remote client login; the realm declaration would have occurred at that point. By the time the EJB calls would occur, the principals would have been populated in the subject.

The ejb-jar.xml (like the web.xml) requires <security-role> declarations with the list of roles being used. Additional security may be imposed on the ability to call specific methods on an EJB, such as those shown here:

<ejb-jar 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/ejb-jar_2_1.xsd";
      version="2.1">

      <enterprise-beans>
          ...
          <session>
            <ejb-name>MyStatelessBean</ejb-name>
             ...
            <security-identity>
                <use-caller-identity/>
            </security-identity>
          </session>
      </enterprise-beans>

      <assembly-descriptor>
          <security-role>
             <role-name>superuser</role-name>
          </security-role>

          <method-permission>
             <description>The description</description>
             <role-name>superuser</role-name>
             <method>
                 <ejb-name>MyStatelessBean</ejb-name>
                 <method-intf>Remote</method-intf>
                 <method-name>secureMethod</method-name>
             </method>
          </method-permission>
          ...
      </assembly-descriptor>
</ejb-jar>

The Geronimo security descriptor is nearly identical to the Web’s. In fact, the geronimo-application .xml can contain a Geronimo Web descriptor, EJB descriptor, and security descriptor. Notice in the following example, geronimo-application.xml, that the security descriptor is the same as the Web example but has been placed on its own in this plan file, while modularizing the Web and EJB code:

<?xml version="1.0" encoding="UTF-8"?>
<application
    xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-1.1"
    configId="MyEJBWebApplication"
    parentId="geronimo/j2ee-security/1.1/car">
    <moduleId>
       <groupId></groupId>
       <artifactId>MyEJBWebApplication</artifactId>
        <version></version>
       <type>car</type>
    </moduleId>

    <!-- OpenEJB Configuration Here -->
    <module>
        <ejb>my-ejbs.jar</ejb>
        <openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar-2.1">

     ...

        </openejb-jar>
    </module>

    ...

    <!-- Web descriptor here" no need for a geronimo-web.xml now -->
    <module>
        <web>SecureWebApp.war</web>
        <web-app xmlns="http://geronimo.apache.org/xml/ns/web/tomcat-1.1">
            <context-prioerty-classloader>false</context-priority-classloader>
            <context-root>/SecureWebApp </context-root>
            <context-priority-classloader>false</context-priority-classloader>
            <security-realm-name>my-new-realm</security-realm-name>

        </web-app>
    </module>

    <!-- BEGIN SECURITY DESCRIPTOR -->
    <security>
        <default-principal>
            <principal name="anonymous"
class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
            />
        </default-principal>
        <role-mappings>
            <role role-name="superuser">
               <principal name="admin" designated-run-as="true"
class="org.apache.geronimo.security.realm.providers.GeronimoGroupPrincipal"
               />
               <principal name="system"
class="org.apache.geronimo.security.realm.providers.GeronimoUserPrincipal"
               />
            </role>
        </role-mappings>
    </security>
    <!-- END SECURITY DESCRIPTOR -->

</application>

The Web module still contains the reference to the <security-realm-name>, since it will handle the authentication. The ejb-jar.xml file then handles the roles mapped from the geronimo-application .xml for the authorization to the roles and method execution permissions.

Both the Web and EJB security configurations are very similar from a configuration perspective with respect to the security descriptor. Each of the specification-compliant deployment descriptors (web.xml and ejb-jar.xml) has many more options that you can configure that are beyond the scope of this book. Material on specification security handling can be obtained from books on EJB and servlets.

Security Descriptor and Declaration

The security descriptor is a schema that allows you to control the application side of security to be used in conjunction with security realms and configurations that have been set up on the server side. As shown in the previous section, the security descriptor can be placed in just about any plan, but typically it is used in a Web’s geronimo-web.xml plan or an EAR file’s geronimo-application.xml plan. This section provides a reference for the security descriptor, and each element is listed in alphabetical order. The security descriptor begins with the <security> element

Portions of this section’s table descriptions are taken directly from the geronimo-securiy-1.1.xsd, Copyright 2004-2005, The Apache Software Foundation.

The <default-principal> Element

This is the principal to use for unauthenticated access of resources.

Table 15-7: The <default-principal> Element Open table as spreadsheet
Elements | Description
<principal> | Required only if the <login-domain-principal> or <realm-principal> is not used. Represents the principal to use for all unauthenticated access to resources.
<login-domain-principal> | Required only if the <principal> or <realmprincipal> is not used. Represents the principal to use for all unauthenticated access to resources.
<realm-principal> | Required only if the <login-domain-principal> or <principal> is not used. Represents the principal to use for all unauthenticated access to resources.
<description> | Optional. May have one or more of these elements. Represents the text-based description of the default principal.
<named-username-password-credential> | Optional. Allows you to create a named username/credential that can be carried along with the default principal. This can give your applications access to these credentials if needed.

The <description> Element

This is an optional element in all cases that allows for free-form text to annotate and describe the element section.

The <distinguished-name > Element

This provides the ability to match the distinguished name (DN) on a SSL certificate, with a presented client certificate. If the DN matches the certificate, the user is considered a part of the role.

Table 15-8: The <distinguished-name> Element Open table as spreadsheet
Attributes | Description
name | Required. The fully qualified distinguished name that matches the SSL certificate.
designated-run-as | Optional. May be true or false. Defaults to false. Set this attribute to “true” if this principal is to be used as the run-as principal for this role.
Open table as spreadsheet
Elements | Description
<description> | Optional. May have one or more of these elements. Represents the text-based description of the distinguished name.

The <login-domain-principal> Element

This ensures that the referenced principal is associated with a particular login domain.

Table 15-9: The <login-domain-principal> Element Open table as spreadsheet
Attributes | Description
class | Required. Class for the principal. May be just about any principal-based class. Geronimo’s JACC typically will use org.apache.geronimo.security.realm.providers .GeronimoUserPrincipal for users and org.apache .geronimo.security.realm.providers.Geronimo UserPrincipal for groups.
name | Required. Principal name.
designated-run-as | Optional. May be true or false. Defaults to false. Set this attribute to true if this principal is to be used as the run-as principal for this role.
domain-name | Required. Login domain name.
Open table as spreadsheet
Elements | Description
<description> | Optional. May have one or more of these elements. Represents the text-based description of the principal.

The <named-username-password-credential> Element

This allows you to create a named username/credential that can be carried along with the default principal. This can give your applications access to these credentials if needed.

Table 15-10: The <named-username-password-credential> Element Open table as spreadsheet
Elements | Description
<name> | Required. The name associated with the username/password grouping.
<username> | Required. Username.
<password> | Required. Password.

The <principal> Element

This is the principal representation for the authenticated user.

Table 15-11: The <principal> Element Open table as spreadsheet
Attributes | Description
class | Required. Class for the principal. May be just about any principal-based class. Geronimo’s JACC typically will use org.apache.geronimo.security.realm.providers .GeronimoUserPrincipal for users and org.apache .geronimo.security.realm.providers.Geronimo UserPrincipal for groups.
name | Required. Principal name.
designated-run-as | Optional. May be true or false. Defaults to false. Set this attribute to true if this principal is to be used as the run-as principal for this role.
Open table as spreadsheet
Elements | Description
<description> | Optional. Text-based description of the principal.

The <realm-principal> Element

This ensures that the referenced principal is associated with a particular realm and login domain.

Table 15-12: The <realm -principal> Element Open table as spreadsheet
Attributes | Description
class | Required. Class for the principal. May be just about any principal-based class. Geronimo’s JACC typically will use org.apache.geronimo.security.realm.providers .GeronimoUserPrincipal for users and org.apache .geronimo.security.realm.providers.Geronimo UserPrincipal for groups.
name | Required. Principal name.
designated-run-as | Optional. May be true or false. Defaults to false. Set this attribute to true if this principal is to be used as the run-as principal for this role.
domain-name | Required. Login domain name.
realm-name | Required. Realm name.
Open table as spreadsheet
Elements | Description
<description> | Optional. Text-based description of the principal.

The <role> Element

This element makes up the different principals to constitute the role. This element may contain any number of principal types.

Table 15-13: The <role> Element Open table as spreadsheet
Attributes | Description
role-name | Required. Unique name to identify the role.
Open table as spreadsheet
Elements | Description
<description> | Optional. May contain more than one of these elements. Text-based description of the role.
<realm-principal> | Optional. May contain more than one of these elements. One or more realm principals to constitute the role.
<login-domain-principal> | Optional. May contain more than one of these elements. One or more login domain principals to constitute the role.
<principal> | Optional. May contain more than one of these elements. One or more principals to constitute the role.
<distinguished-name> | Optional. May contain more than one of these elements. One or more distinguished names to constitute the role. Provides the ability to match the distinguished name (DN) on a SSL certificate, with a presented client certificate. If the DN matches the certificate, the user is considered a part of the role.

The <role-mapping> Element

This element contains the roles that will be created from the principals within each role.

Table 15-14: The <role-mapping> Element Open table as spreadsheet
Elements | Description
<role> | Required. One or more role elements make up the list of roles that map the principals to each role.

The <security> Element

The <security> element denotes to the deployer that there is a security configuration. Existence of this element forces the EJB and Web containers to set up and implement JACC within their authorization handlers.

Table 15-15: The <security> Element Open table as spreadsheet
Attributes | Description
do-as-currentcaller | Optional. Default is false. If set to true, all work within the Web or EJB containers will be performed by the calling subject.
use-context-handler | Optional. Default is false. If set to true, JACC policies will use PolicyContextHandlers.
default-role | Optional. Used by the deployer to assign method permissions for all of the unspecified methods, either by assigning them to security roles or by marking them as unchecked. If the value of default-role is empty, then the unspecified methods are marked unchecked.
Open table as spreadsheet
Elements | Description
<description> | Optional. Text-based description of the security.
<default-principal> | Required. Principal to use for unauthenticated access of resources.
<role-mapping> | Optional. Enables mapping of principals to roles.
Listing 15-4: geronimo-security-1.1 XML Schema
Image from book
<xsd:schema
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:j2ee="http://java.sun.com/xml/ns/j2ee"
  xmlns:geronimo="http://geronimo.apache.org/xml/ns/security-1.1"
  targetNamespace="http://geronimo.apache.org/xml/ns/security-1.1"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"
  version="1.0">

  <xsd:element name="security" type="geronimo:securityType"/>

  <xsd:element name="default-principal" type="geronimo:default-principalType"/>
  <xsd:complexType name="securityType">
  <xsd:annotation>
    <xsd:documentation>
      Security entries
      If this element is present, all web and EJB modules MUST make the
      appropriate access checks as outlined in the JACC spec.
 </xsd:documentation>
</xsd:annotation>
<xsd:sequence>
  <xsd:element name="description" type="geronimo:descriptionType"
                minOccurs="0" maxOccurs="unbounded"/>
  <xsd:element name="default-principal"
                type="geronimo:default-principalType"/>
  <xsd:element name="role-mappings" type="geronimo:role-mappingsType"
                minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="doas-current-caller" type="xsd:boolean"
                 default="false">
  <xsd:annotation>
     <xsd:documentation>
         Set this attribute to "true" if the work is to be performed
        as the calling Subject.
     </xsd:documentation>
  </xsd:annotation>
</xsd:attribute>
<xsd:attribute name="use-context-handler" type="xsd:boolean"
                 default="false">
  <xsd:annotation>
    <xsd:documentation>
        Set this attribute to "true" if the installed JACC policy
        contexts will use PolicyContextHandlers.
    </xsd:documentation>
  </xsd:annotation>
  </xsd:attribute>
  <xsd:attribute name="default-role" type="xsd:string">
    <xsd:annotation>
      <xsd:documentation>
        Used by the Deployer to assign method permissions for
        all of the unspecified methods, either by assigning them
        to security roles, or by marking them as unchecked.  If
        the value of default-role is empty, then the unspecified
        methods are marked unchecked
      </xsd:documentation>
    </xsd:annotation>
  </xsd:attribute>
</xsd:complexType>

<xsd:complexType name="descriptionType">
  <xsd:simpleContent>
    <xsd:extension base="xsd:string">
      <xsd:attribute ref="xml:lang"/>
    </xsd:extension>
  </xsd:simpleContent>
</xsd:complexType>

<xsd:complexType name="default-principalType">
  <xsd:sequence>
    <xsd:element name="description" type="geronimo:descriptionType"
                  minOccurs="0" maxOccurs="unbounded"/>
    <xsd:choice>
      <xsd:element name="principal" type="geronimo:principalType"/>
      <xsd:element name="login-domain-principal"
                   type="geronimo:loginDomainPrincipalType"/>
      <xsd:element name="realm-principal" type="geronimo:realmPrincipalType"/>
    </xsd:choice>
    <xsd:element name="named-username-password-credential"
               type="geronimo:named-username-password-credentialType"
               minOccurs="0" maxOccurs="unbounded"/>
    </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="named-username-password-credentialType">
  <xsd:sequence>
    <xsd:element name="name" type="xsd:string"/>
    <xsd:element name="username" type="xsd:string"/>
    <xsd:element name="password" type="xsd:string"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="role-mappingsType">
  <xsd:sequence>
    <xsd:element name="role" type="geronimo:roleType"
                  minOccurs="1" maxOccurs="unbounded"/>
  </xsd:sequence>
</xsd:complexType>

<xsd:complexType name="roleType">
  <xsd:sequence>
    <xsd:element name="description" type="geronimo:descriptionType"
                  minOccurs="0" maxOccurs="unbounded"/>
    <xsd:element name="realm-principal" type="geronimo:realmPrincipalType"
                  minOccurs="0" maxOccurs="unbounded"/>
    <xsd:element name="login-domain-principal"
                  type="geronimo:loginDomainPrincipalType"
                  minOccurs="0" maxOccurs="unbounded"/>
    <xsd:element name="principal" type="geronimo:principalType"
                  minOccurs="0" maxOccurs="unbounded"/>
    <xsd:element name="distinguished-name"
                  type="geronimo:distinguishedNameType"
                  minOccurs="0" maxOccurs="unbounded"/>
  </xsd:sequence>
  <xsd:attribute name="role-name" type="xsd:string" use="required"/>
</xsd:complexType>

<xsd:complexType name="realmPrincipalType">
  <xsd:complexContent>
    <xsd:extension base="geronimo:loginDomainPrincipalType">
      <xsd:attribute name="realm-name" type="xsd:string" use="required"/>
    </xsd:extension>
  </xsd:complexContent>
</xsd:complexType>

<xsd:complexType name="loginDomainPrincipalType">
  <xsd:complexContent>
        <xsd:extension base="geronimo:principalType">
          <xsd:attribute name="domain-name" type="xsd:string" use="required"/>
        </xsd:extension>
      </xsd:complexContent>
    </xsd:complexType>

    <xsd:complexType name="principalType">
      <xsd:sequence>
        <xsd:element name="description" type="geronimo:descriptionType"
                      minOccurs="0" maxOccurs="unbounded"/>
      </xsd:sequence>
      <xsd:attribute name="class" type="xsd:string" use="required"/>
      <xsd:attribute name="name" type="xsd:string" use="required"/>
      <xsd:attribute name="designated-run-as" type="xsd:boolean" default="false">
        <xsd:annotation>
          <xsd:documentation>
            Set this attribute to "true" if this principal is to be
            used as the run-as principal for this role.
          </xsd:documentation>
        </xsd:annotation>
      </xsd:attribute>
    </xsd:complexType>

    <xsd:complexType name="distinguishedNameType">
      <xsd:sequence>
        <xsd:element name="description" type="geronimo:descriptionType"
                      minOccurs="0" maxOccurs="unbounded"/>
      </xsd:sequence>
      <xsd:attribute name="name" type="xsd:string" use="required"/>
      <xsd:attribute name="designated-run-as" type="xsd:boolean" default="false">
        <xsd:annotation>
          <xsd:documentation>
            Set this attribute to "true" if this principal is to be
            used as the run-as principal for this role.
          </xsd:documentation>
        </xsd:annotation>
      </xsd:attribute>
    </xsd:complexType>

</xsd:schema>
Image from book

A final advanced technique covered here is the ability to override the authorization GBean used by the Geronimo server.

Overriding the Default Behavior of the SecurityService GBean

The Geronimo server JACC component is handled and set up by default with the SecurityService GBean using the SecurityServiceImpl class. Geronimo supports the ability to allow for pluggable policy implementation and configuration factory classes. Geronimo currently comes preconfigured to work with its own default implementation, with the org.apache.geronimo.jacc.GeronimoPolicy and org.apache.geronimo.jacc.GeronimoPolicyConfigurationFactory. These work with the deployers to allow you to declare advanced JACC principal-role mappings and permissions in your plans. These are already configured in Geronimo and are set with the policyConfigurationFactory and policyProvider attributes in the SecurityService GBean, as shown here:

<gbean name="SecurityService"
class="org.apache.geronimo.security.SecurityServiceImpl">
    <reference name="ServerInfo">
      <module>geronimo/j2ee-system/1.1/car</module>
      <name>ServerInfo</name>
    </reference>
    <attribute name="policyConfigurationFactory">
org.apache.geronimo.security.jacc.GeronimoPolicyConfigurationFactory</attribute>
    <attribute name="policyProvider">
org.apache.geronimo.security.jacc.GeronimoPolicy</attribute>
</gbean>

You may create your own policy or factory to do enhanced policy handling, or possibly to log all security access to your applications, and plug them in by changing the SecurityService attributes to use your own versions. In addition, you can override the GBean’s attributes by setting system properties when you launch Geronimo. This means that if you set the system property on the command line, the GBean will ignore its own attributes. For example, if you created your own policy and policy configuration factory, called com.example.MyPolicy and com.example.MyPolicyConfigurationFactory, you could use these by running Geronimo with the following command (all on one line):

java –jar bin/server.jar -Djavax.security.jacc.policy.provide=com.example.MyPolicy
-Djavax.security.jacc.PolicyConfigurationFactory.provider=
com.example.MyPolicyConfigurationFactory

You may also set up SSL configurations with the SecurityService GBean or command-line parameters, such as the key store, the trust store, and their passwords. Thus, SecurityServiceImpl is the JACC Service handler and allows for setting container-wide SSL properties. Table 15-16 shows the system properties and the GBean attributes they override.

Table 15-16: SecurityService GBean Open table as spreadsheet
Type | Name | Req | Description
A | policy Configuration factory | No | The class name for the provider configuration to use. May be also set or overridden Factory with the javax.security.jacc.Policy ConfigurationFactory.provider system property.
A | policyProvider | No | The class name for the policy provider to use. May be also set or overridden with the javax.security.jacc.policy.provider system property.
A | keyStore | No | The path and filename of the key store file. Relative paths will be relative to $GERONIMO_HOME. May be also set or overridden with the javax .net.ssl.keyStore system property.
A | keyStorePassword | No | The password of the server certificate that is stored in the key store file. May be also set or overridden with the javax.net.ssl.key-StorePassword system property.
A | trustStore | No | The path and filename of the key store file. Relative paths will be relative to $GERONIMO_HOME. May be also set or overridden with the javax.net.ssl.trustStore system property.
A | trustStorePassword | No | The password of the server certificate that is stored in the trust store file. May be also set or overridden with the javax.net.ssl.trust-StorePassword system property.
R | ServerInfo | Yes | Reference to a ServerInfo GBean.
Legend Type: (A) - Attribute, (R) - Reference to GBean Req: (Yes) - parameter is required, (No) - not required


Locking Down Geronimo

By default, Geronimo comes with many default settings and configurations tuned for ease of use. They are not, in most cases, designed to provide a secured server out of the box.

In a production environment, administrators and system integrators should be aware of potentially exploitable defaults - and perform a lockdown of the server.

Based experience in working with Geronimo, here is a small punch list to consider when making your server available in a production environment:

  • Change the administrator username and password. The var/security/users.properties and var/security/groups.properties has the user system and password manager set to be in the admin group. Consider changing the username and password and placing this new user in the admin group.

  • Consider running Geronimo with a Web server running mod_jk or equivalent. This will allow you to only let certain URLs through to the Web component. This can prevent outsiders from accessing the console or other private applications.

  • Change the Apache Directory server’s administrator password. The admin user’s DN is uid=admin,ou=system and the password is secret.

  • Consider changing the port Apache Directory server runs on. It currently runs on port 1389 to get around the need to run as a superuser to access the LDAP well-known port of 389.

  • Examine the list of components that come with Geronimo and decide if they are really necessary. Do you really need the LDAP server? Do you really need all of the demo applications running?

  • Examine the ActiveMQ JMS topics and queues. Are they secure? Are any open? Do you need to change credentials to access these queues?

As a final general note, always remember your firewall. Only let in those ports to access Geronimo that your users will need for accessing your applications.


Summary

Geronimo offers a complete J2EE 1.4 standards-compliant security implementation. It supports JACC and JAAS through services and GBeans This chapter described the Geronimo security architecture and how to configure the server to use JAAS login configurations, LoginModules, and how to leverage JACC with pluggable policy components. These configurations were shown using Geronimo’s GBean components. Some more advanced configurations, such as LoginModule chaining, were covered. The discussion also covered the plan’s security deployment descriptor, used to protect and secure your applications.

Security is one of the most critical aspects of application server administration. Understanding how to properly configure the security and have your applications correctly leverage the security configuration are critical to protecting your resources and intellectual property. This chapter covered in detail the Geronimo security model, related concepts, and techniques. You can now be confident in applying them when configuring security for your applications.


Chapter 16: Configuring, Deploying, and Using JMS Resources with Apache ActiveMQ

Chapter 12 focused on the deployment of an Enterprise Application in Geronimo. This chapter builds on those concepts and takes things a step further by focusing on enterprise messaging through the use of the Java Message Service (JMS). As the Java messaging standard, JMS is an integral part of the J2EE 1.4 specification. JMS provides an enterprise messaging API that supports both the queuing and publish-subscribe styles of messaging with guaranteed message delivery, receipt notification, and transactions. Through the use of JMS, business applications can exchange critical business events and data in an asynchronous manner. Geronimo provides support for JMS via Apache ActiveMQ.

ActiveMQ is an enterprise-level, Open Source message broker that provides high-performance, practically unlimited scalability, high reliability, and configuration flexibility. ActiveMQ is a JMS 1.1 message broker and supports TCP, UDP, SSL, HTTP, multicasting, Jabber (XMPP), Java Reliable Multicast Service (JRMS), JXTA, XA, J2EE Connector Architecture 1.5, and much, much more. Features include queues, topics, durable and nondurable messaging with pluggable security and persistence, wildcards, selectors, composite destinations, and XPath. ActiveMQ also supports high-speed journaling for the persistence of messages when handling very high throughput. Additional information on ActiveMQ can be found at the ActiveMQ Web site (www.activemq.org).

The ActiveMQ Message Broker Architecture

This section takes a brief look at the ActiveMQ architecture at a very high level. Figure 16-1 shows a diagram of the ActiveMQ architecture. Notice that the topology is centered upon the Topic Region and the Queue Region. First, focus on the connectors on the top of the diagram (HTTP, SSL/TCP, STOMP, WS-Notification). These connectors are J2EE Connector Architecture resource adapters. The inbound connections deliver messages to Message Driven Beans, whereas outbound connections provide support for the pooling of ActiveMQ instances. STOMP (Streamlining Text Oriented Messaging Protocol) provides a protocol for interacting with Message-Oriented Middleware from languages other than Java. The WS-Notification connector provides a bridge to the Web Services-Notification specification.

Image from book
Figure 16-1: A diagram of the ActiveMQ architecture

In Figure 16-1, focus on the Network Services (Discovery, DR Clustering, Store & Forward) area on the right-hand side. Discovery refers to the auto-discovery of JMS clients and brokers on the network. DR Clustering refers to disaster recovery and clustering. Disaster recovery (DR) is the notion of configuring a cluster of brokers to replicate messages to another location for purposes of recovery in the event of a major catastrophe. Clustering includes a logical cluster of brokers, a cluster of consumers on a queue, and a network of brokers for massive scalability. Store & Forward refers to the concept of a broker receiving a message, storing it locally, sending it along to another broker, and deleting it only once it has been successfully received.

Now, focus on the bottom portion of Figure 16-1 named Message Store (JDBC, Journal, Cache, VM). These are adapters for various message-persistence mechanisms. JDBC is one option for the persistence of messages to a relational data source. The Journal option utilizes a high-speed journaling solution where messages are written to the journal at a very high rate, and the journal is checkpointed to long-term storage in batches. Cache refers to the caching layer just above the JDBC service and in-VM storage of messages. This diagram comes directly from the ActiveMQ Web site and provides a good high-level overview of the architecture.

This chapter discusses the configuration and deployment of the ActiveMQ message broker and its JMS resources, including connection factories and destinations (queues and topics). There are two pieces of ActiveMQ that matter to Geronimo: the message broker and the resource adapter. The message broker is packaged and deployed as a GBean archive, along with its configuration information. The JMS resources will be packaged and deployed as a resource adapter configuration in compliance with the J2EE Connector Architecture 1.5. These two concepts provide the basis for this chapter.

Upon completing this chapter, you should have a clear understanding of the use of the ActiveMQ message broker within the Geronimo server and how to configure and deploy JMS resources.


ActiveMQ Message Broker Configuration

Geronimo utilizes its GBean architecture to manage the lifecycle of services in the Geronimo server. As described in Chapter 9, XML deployment descriptor files (known as deployment plans, or simply plans) contain all metadata about GBeans and their dependencies. This file is used by an assembly to discover all the dependencies for the ActiveMQ broker to be sure those are all available before attempting to start up an ActiveMQ broker instance. As long as all dependencies are available, the ActiveMQ broker is started and a message is printed to the terminal indicating that the ActiveMQ broker is running. See the bold text in the following example output when starting Geronimo to see this message:

$ ./bin/geronimo.sh run
Using GERONIMO_BASE:    /Users/bsnyder/geronimo-1.1
Using GERONIMO_HOME:    /Users/bsnyder/geronimo-1.1
Using GERONIMO_TMPDIR:  /Users/bsnyder/geronimo-1.1/var/temp
Using JRE_HOME:
/System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home
Booting Geronimo Kernel (in Java 1.4.2_09)...
Starting Geronimo Application Server v1.1
[**********************] 100%  87s Startup complete
  Listening on Ports:
    1099 0.0.0.0 RMI Naming
    1527 0.0.0.0 Derby Connector
    4201 0.0.0.0 ActiveIO Connector EJB
    4242 0.0.0.0 Remote Login Listener
    8009 0.0.0.0 Jetty Connector AJP13
    8080 0.0.0.0 Jetty Connector HTTP
    8443 0.0.0.0 Jetty Connector HTTPS
    9999 0.0.0.0 JMX Remoting Connector
   61616 0.0.0.0 ActiveMQ Message Broker Connector

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

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

Geronimo Application Server started

The bold text indicates that the ActiveMQ broker has been started and is running on port 61616. This is simply the default port on which the ActiveMQ broker typically runs and can be changed as needed via the var/config/config.xml file.

Listing 16-1 shows the deployment plan for the ActiveMQ broker inside of Geronimo. Note that none of the deployment plans for any specific modules are included in the 1.1 binary download of Geronimo. To see this and other deployment plans, you will need to see the Geronimo Subversion repository (http://svn.apache.org/repos/asf/geronimo). As of this writing, the deployment plan below is located in configs/activemq-broker/target/plan/plan.xml, but only after a clean build of Geronimo.

Listing 16-1: The ActiveMQ Broker Plan
Image from book
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1">
  <!--management-->
  <environment>
    <moduleId>
      <groupId>geronimo</groupId>
      <artifactId>activemq-broker</artifactId>
      <version>1.1</version>
      <type>car</type>
    </moduleId>
    <dependencies>
      <dependency>
        <groupId>geronimo</groupId>
        <artifactId>system-database</artifactId>
        <type>car</type>
      </dependency>
      <dependency>
        <groupId>activemq</groupId>
        <artifactId>activemq-core</artifactId>
        <type>jar</type>
        <import>classes</import>
      </dependency>
      <dependency>
        <groupId>activemq</groupId>
        <artifactId>activemq-gbean-g1_1</artifactId>
        <type>jar</type>
        <import>classes</import>
      </dependency>
      <dependency>
        <groupId>activemq</groupId>
        <artifactId>activemq-gbean-management-g1_1</artifactId>
        <type>jar</type>
        <import>classes</import>
      </dependency>
      <dependency>
        <groupId>activeio</groupId>
        <artifactId>activeio</artifactId>
        <type>jar</type>
        <import>classes</import>
      </dependency>
    </dependencies>
      <hidden-classes/>
      <non-overridable-classes/>
    </environment>
    <gbean name="ActiveMQManager"
class="org.activemq.gbean.management.ActiveMQManagerGBean"/>
  <!--message broker-->
  <gbean name="ActiveMQ" class="org.activemq.gbean.ActiveMQContainerGBean">
    <attribute name="brokerName">possibly-unique-broker</attribute>
    <reference name="persistenceAdapter">
      <name>ActiveMQ.cache</name>
    </reference>
    <reference name="JMSManager">
      <name>ActiveMQManager</name>
    </reference>
    <dependency>
      <name>SystemProperties</name>
    </dependency>
  </gbean>
  <gbean name="ActiveMQ.cache"
class="org.activemq.store.cache.SimpleCachePersistenceAdapterGBean">
    <attribute name="cacheSize">10000</attribute>
    <reference name="longTermPersistence">
      <name>ActiveMQ.journal</name>
    </reference>
  </gbean>
  <gbean name="ActiveMQ.journal"
class="org.activemq.store.journal.JournalPersistenceAdapterGBean">
    <reference name="serverInfo">
      <name>ServerInfo</name>
    </reference>
    <attribute name="directory">var/activemq/journal</attribute>
    <attribute name="journalType">default</attribute>
    <reference name="longTermPersistence">
      <name>ActiveMQ.jdbc</name>
    </reference>
  </gbean>
  <gbean name="ActiveMQ.jdbc"
class="org.activemq.store.jdbc.JDBCPersistenceAdapterGBean">
    <reference name="dataSource">
      <name>SystemDatasource</name>
    </reference>
  </gbean>
  <gbean name="ActiveMQ.tcp.default"
class="org.activemq.gbean.ActiveMQConnectorGBean">
    <attribute name="protocol">tcp</attribute>
    <attribute name="host">localhost</attribute>
    <attribute name="port">61616</attribute>
    <reference name="activeMQContainer">
      <name>ActiveMQ</name>
    </reference>
  </gbean>
  <gbean name="ActiveMQ.vm.localhost"
class="org.activemq.gbean.ActiveMQConnectorGBean">
    <attribute name="protocol">vm</attribute>
    <attribute name="host">localhost</attribute>
    <attribute name="port">-1</attribute>
    <reference name="activeMQContainer">
      <name>ActiveMQ</name>
    </reference>
  </gbean>
  <gbean name="SystemProperties"
class="org.apache.geronimo.system.properties.SystemProperties">
    <attribute name="systemProperties">activemq.broker.disable-clean
shutdown=true</attribute>
  </gbean>
</module>
Image from book

The deployment plan for the ActiveMQ displayed in Listing 16-1 focuses on the definition of the GBeans used by the Geronimo kernel to start the ActiveMQ broker. For more information on GBeans, see Chapter 5. Understanding the plan in Listing 16-1 will assist you in understanding the ActiveMQ broker configuration for Geronimo. Table 16-1 provides a description of the ActiveMQ plan in Listing 16-1.

Table 16-1: Overview of the ActiveMQ Broker Plan Open table as spreadsheet
Component/GBean | Name Description
environment | An encapsulating root element for the module plan file.
moduleId | A container element for the groupId, artifactId, and version of the module. Together these items form the moduleId.
dependencies | This element holds all dependency and class loader information for the module.
hidden-classes | A list of classes that will never be loaded from parent Class-Loaders of this module. The classes are specified in zero or more child filter elements, where each filter element specifies a fully qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed here will be treated as hidden.
non-overridable-classes | A list of classes that will only be loaded from parent Class-Loaders of this module (never from the module’s own ClassLoader). Just as with the hidden-classes element, the classes are specified in zero or more child filter elements, where each filter element specifies a fully qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed here will be treated as hidden.
ActiveMQManager | The ActiveMQManager is a management interface for the ActiveMQ message broker.
ActiveMQ | The ActiveMQ GBean wraps the ActiveMQ message broker to handle its lifecycle. This GBean defines a reference element, namely the persistenceAdapter. Notice the gbean-name for the persistenceAdapter. It's a reference to another GBean. It’s pointing to a GBean whose name begins with the string ActiveMQ.cache. This resolves to the GBean element whose name is ActiveMQ.cache.
ActiveMQ.cache | The ActiveMQ.cache GBean sits above the persistence GBean (ActiveMQ.jdbc) to providing caching facilities. It defines an attribute named cacheSize and a reference to the ActiveMQ.journal GBean.
ActiveMQ.journal | The ActiveMQ.journal is used for short-term, high-performance persistence and is checkpointed to the database periodically. It defines an attributes named directory and journalType, and also a reference to the ActiveMQ.jdbc GBean.
ActiveMQ.jdbc | The ActiveMQ.jdbc GBean identifies the long-term message persistence configuration using a JDBC data source. It simply refers to another GBean whose unique ID is SystemDatabase.
geronimo.tcp.default | A J2EE connector providing a TCP-based connection to the ActiveMQ message broker.
geronimo.vm.localhost | A J2EE connector providing a local connection to the ActiveMQ message broker.
SystemProperties | A convenience component to handle system properties. This component allows system properties to be set in deployment plans instead of in a very long string on the command line when starting the JVM. For ActiveMQ, there is a property listed here named activemq.broker.disable-clean-shutdown and it is set to true. This property tells the Geronimo lifecycle to not perform a clean shutdown on ActiveMQ.

This plan controls how the message broker is configured by default. You can customize this default configuration using the config.xml file, covered next.

Customizing the Message Broker

In Geronimo 1.1, there are two ways to make customizations to any module:

  • Using the config.xml file

  • Using the deployment plan for the given module

Each method of customization has its advantages and disadvantages.

Important-When Does the config.xml File Not Take Precedence?

Under most circumstances, the config.xml file rules supreme when it comes to customizing a given module. But there are times when changes to the config.xml will not have the desired affect. An example of this is the removal of a dependency that is defined in a configuration’s plan.

For example, removing the SystemDatabase dependency from the ActiveMQ broker by removing it from the config.xml will be overridden by the ActiveMQ broker configuration’s explicit dependency on it from within its plan. In other words, since the dependency on the SystemDatabase already exists from within the ActiveMQ broker module’s deployment plan, it cannot be removed per se. It can, however, be redefined in the config.xml by creating an entirely new definition for a configuration matching the SystemDatabase’s exact configuration name.

Customization Using the config.xml File

The binary distribution for Geronimo contains a file in the var/config directory named config.xml (var/config/config.xml) that is specifically for customizing module configurations. No matter whether a module is customized through the use of the config.xml or the module’s corresponding deployment plan, the config.xml takes precedence unless the module’s deployment plan contains dependencies that may override changes to the given plan. For more information on this, see the sidebar “When Does the config.xml File Not Take Precedence?”

The following example is an excerpt from the default config.xml file that controls the ActiveMQ broker configuration:

...
    <module name="geronimo/activemq-broker/1.1-rc1/car">
        <gbean name="ActiveMQ.tcp.default">
            <attribute name="host">0.0.0.0</attribute>
            <attribute name="port">61616</attribute>
        </gbean>
    </module>
...

The portion of the config.xml displayed here applies to a module with the unique ID of geronimo/activemq-broker/1.1/car. This is just a simple unique string ID that points to the ActiveMQ broker module. It comes directly from the module’s deployment plan, which is discussed in the next section. Next is a GBean whose name is ActiveMQ.tcp.default. This is the unique name for a particular GBean in the ActiveMQ broker configuration in Listing 16-1. The attribute elements defined within the GBean element apply to properties in the ActiveMQ.tcp.default GBean. Any attributes listed here can be customized manually. For example, if the port attribute must be changed, this is the place to do it. For example, to change the port number used by ActiveMQ from 61616 to 31313, just override the necessary attribute, like this:

...
<module name="geronimo/activemq-broker/1.1-rc1/car">
        <gbean name="ActiveMQ.tcp.default">
            <attribute name="protocol">tcp</attribute>
            <attribute name="host">localhost</attribute>
            <attribute name="port">31313</attribute>
      </gbean>
      </module>
...

Now, when Geronimo is started up, the port on which ActiveMQ runs is 31313:

Using GERONIMO_BASE:    /Users/bsnyder/geronimo-1.1
Using GERONIMO_HOME:    /Users/bsnyder/geronimo-1.1
Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp
Using JRE_HOME:
/System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home
Booting Geronimo Kernel (in Java 1.4.2_09)...
Starting Geronimo Application Server v1.1
[**********************] 100%  87s Startup complete
  Listening on Ports:
    1099 0.0.0.0 RMI Naming
    1527 0.0.0.0 Derby Connector
    4201 0.0.0.0 ActiveIO Connector EJB
    4242 0.0.0.0 Remote Login Listener
    8009 0.0.0.0 Jetty Connector AJP13
    8080 0.0.0.0 Jetty Connector HTTP
    8443 0.0.0.0 Jetty Connector HTTPS
    9999 0.0.0.0 JMX Remoting Connector
   31313 0.0.0.0 ActiveMQ Message Broker Connector

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

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

Geronimo Application Server started

This is just a simple example of changing an attribute that has little impact on the actual GBean that’s running in Geronimo to control the ActiveMQ broker because it just changes an integer. If the protocol must be changed, then further customization in the config.xml file is necessary.

In addition to customizing attributes on a GBean, new GBeans can also be defined in the config.xml. By default, there are two network connectors installed for the ActiveMQ broker: an in-VM connector (whose name is ActiveMQ.vm.localhost) and a TCP connector (whose name is ActiveMQ.tcp.default). Additional connectors can be added via the config.xml. However, as noted earlier, adding a new network connector (or even changing an existing one) requires additional customization. For example, a new connector for the STOMP protocol can be added, but it requires more than the previous example. Following is an example of defining a new network connector to provide the STOMP protocol for ActiveMQ:

...
<module name="geronimo/activemq-broker/1.1/car">
  <gbean gbeanInfo="org.activemq.gbean.ActiveMQConnectorGBean"
name="geronimo/activemq
broker/1.1/car?JMSServer=ActiveMQ,ServiceModule=geronimo/activemq-broker/1.1/car,j2
eeType=GBean,name=ActiveMQ.stomp">
      <attribute name="protocol">stomp</attribute>
      <attribute name="host">localhost</attribute>
      <attribute name="port">21212</attribute>
      <reference name="activeMQContainer">
        <pattern>
          <groupId>geronimo</groupId>
          <artifactId>activemq-broker</artifactId>
          <version>1.1</version>
          <type>car</type>
          <name>ActiveMQ</name>
        </pattern>
      </reference>
    </gbean>
</module>
...

This example defines a new GBean for a new connector to make use of the STOMP protocol. By adding this definition to the config.xml, the new connector is deployed to handle JMS requests over STOMP on port 21212.

Deploying Customizations to the config.xml File

To apply changes to the config.xml file, simply cycle the server. When working from the Geronimo source code, beware that the config.xml file is regenerated during every build, and any changes made to it will be overwritten upon recompile. Be sure to back up any changes before rebuilding from source.

The other prescribed manner in which to change a module configuration is to use the module’s deployment plan.

Customization Using the Deployment Plan

The configuration of the ActiveMQ broker is housed entirely in the deployment plan that is displayed in Listing 16-1 and is described in Table 16-1. The plan is an XML descriptor that contains the necessary dependencies in the form of both JARs and other GBeans. However, this plan file is not included in the 1.1 binary download of Geronimo. This file can be found in the Geronimo source code, but full customization using this file requires a rebuild of the configuration from the source.

For the purposes of customizing the message broker, the procedure outlined using the config.xml file in the previous section should be sufficient.

Important-Where Are the Module Deployment Plans?

In Geronimo 1.1, the module deployment plans are not included in the binary download. These files are only found in the source download because they need to be recompiled using the Geronimo build.

Deploying a Message Broker Configuration

Although changes to the config.xml only require the server to be cycled, there are situations where ActiveMQ may need to be deployed. There are two ways to deploy the ActiveMQ Message Broker in Geronimo:

  • Via the command line using the Geronimo deployer

  • Via the Geronimo console

Actually, any JMS 1.1–compliant broker can be deployed in Geronimo. All that is required is to create the proper GBeans to wrap it and make it part of the Geronimo lifecycle. Let’s examine these two deployment techniques.

Deploying ActiveMQ Using the Command-Line Deployer

Deploying the ActiveMQ module may be necessary if, for some reason, it is undeployed. Using the command-line deployer is rather straightforward, and there is a convenience script for this very purpose. Using the deploy.sh script in the bin directory, modules can be easily deployed via the command line. Most typically, a module will have a deployment plan, but there are cases where the deployment plan is actually contained inside the module.

Following is an example of using the deploy.sh script to stop, and then start, the ActiveMQ module. First, you must determine the name of the module you’d like to stop. This can be done using the deployer’s list-modules function, as demonstrated here:

$ ./bin/deploy.sh --user system --password manager list-modules
Using GERONIMO_BASE:    /Users/bsnyder/geronimo-1.1
Using GERONIMO_HOME:    /Users/bsnyder/geronimo-1.1
Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp
Using JRE_HOME:
/System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home
Found 32 modules
  + geronimo/activemq-broker/1.1/car
  + geronimo/axis/1.1/car
  + geronimo/axis-deployer/1.1/car
  + geronimo/client-deployer/1.1/car
  + geronimo/geronimo-gbean-deployer/1.1/car
  + geronimo/hot-deployer/1.1/car
  + geronimo/j2ee-deployer/1.1/car
  + geronimo/j2ee-security/1.1/car
  + geronimo/j2ee-server/1.1/car
+ geronimo/j2ee-system/1.1/car
+ geronimo/jetty/1.1/car
+ geronimo/jetty-deployer/1.1/car
+ geronimo/openejb/1.1/car
+ geronimo/openejb-deployer/1.1/car
+ geronimo/remote-deploy-jetty/1.1/car @ http://rattlesnake:8080/remote-deploy
+ geronimo/rmi-naming/1.1/car
+ geronimo/sharedlib/1.1/car
+ geronimo/system-database/1.1/car
+ geronimo/webconsole-jetty/1.1/car
    `-> framework.war @ http://rattlesnake:8080/console
    `-> standard.war @ http://rattlesnake:8080/console-standard
+ geronimo/welcome-jetty/1.1/car @ http://rattlesnake:8080/
  geronimo/activemq/1.1/car
  geronimo/client/1.1/car
  geronimo/client-corba/1.1/car
  geronimo/client-security/1.1/car
  geronimo/client-system/1.1/car
  geronimo/j2ee-corba/1.1/car
  geronimo/javamail/1.1/car
  geronimo/online-deployer/1.1/car
  geronimo/shutdown/1.1/car
  geronimo/uddi-jetty/1.1/car
  geronimo/upgrade/1.1/car
  geronimo/upgrade-cli/1.1/car

The list-modules function states that it found 32 modules, but only those with a preceding plus sign (+) are actually started. In this case, the goal here is to stop the ActiveMQ broker, which happens to be the first module listed. Now, the module can be stopped using its unique name:

$ ./bin/deploy.sh --user system --password manager stop geronimo/activemq-
broker/1.1/car
Using GERONIMO_BASE:    /Users/bsnyder/geronimo-1.1
Using GERONIMO_HOME:    /Users/bsnyder/geronimo-1.1
Using GERONIMO_TMPDIR:  /Users/bsnyder/geronimo-1.1/var/temp
Using JRE_HOME:
/System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home

    Stopped geronimo/activemq-broker/1.1/car

Once the module has been stopped, it can easily be started again, as shown here:

$ ./bin/deploy.sh --user system --password manager start geronimo/activemq-
broker/1.1/car
Using GERONIMO_BASE:    /Users/bsnyder/geronimo-1.1
Using GERONIMO_HOME:    /Users/bsnyder/geronimo-1.1
Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp
Using JRE_HOME:
/System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home

    Started geronimo/activemq-broker/1.1/car
Important-What Do the Contents of the Module Look Like?

Following are the contents of the activemq-broker module:

activemq-broker-1.1.car
activemq-broker-1.1.car/META-INF
activemq-broker-1.1.car/META-INF/config.info
activemq-broker-1.1.car/META-INF/config.ser
activemq-broker-1.1.car/META-INF/config.ser.sha1

Notice that the module itself contains a serialized copy of the module, along with some metadata and a Secure Hash Algorithm (SHA) cryptographic file for validation purposes. This module can be found in the repository directory once the module is deployed within Geronimo.

The deployer can also be used to deploy and undeploy modules within Geronimo. As an example, to undeploy the ActiveMQ module, simply use its deployment plan, as demonstrated here:

$ ./bin/deploy.sh --user system --password manager undeploy geronimo/activemq-
broker/1.1/car
Using GERONIMO_BASE:   /Users/bsnyder/geronimo-1.1
Using GERONIMO_HOME:   /Users/bsnyder/geronimo-1.1
Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp
Using JRE_HOME:
/System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home
    Module geronimo/activemq-broker/1.1/car unloaded.
    Module geronimo/activemq-broker/1.1/car uninstalled.

    Undeployed geronimo/activemq-broker/1.1/car

Note that undeploying any module actually deletes that module, and it cannot be recovered. To deploy the module, both the module itself and its deployment plan are required by the deployer. As long as these two items are present, they can be fed to the deployer using the deploy function:

$ ./bin/deploy.sh --user system --password manager deploy /path/to/activemq-broker-
1.1.car /path/to/activemq-broker-plan.xml
Using GERONIMO_BASE:   /Users/bsnyder/geronimo-1.1
Using GERONIMO_HOME:   /Users/bsnyder/geronimo-1.1
Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp
Using JRE_HOME:
/System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home
    Deployed geronimo/activemq-broker/1.1/car

Now, the ActiveMQ broker is deployed again and ready to be used.

The Geronimo deployer is a very powerful tool for working with modules.

The second method of deploying the ActiveMQ module is via the Web-based management console that ships with Geronimo.

Deploying ActiveMQ Using the Management Console

Once ActiveMQ is started up, its configuration can be managed from the Geronimo Web console. When you click the link under the Applications category named System Modules, the screen shown in Figure 16-2 is what will appear.

Image from book
Figure 16-2: A listing of the system modules with the ActiveMQ module in a running state

This screen lists all modules that are currently deployed in Geronimo. Notice that each module’s state is listed under the column aptly named State. The ActiveMQ module is deployed as can be seen by its unique ID of geronimo/activemq-broker/1.1/car and whose state is listed as running. To stop this module, simply click the link named Stop. Upon doing so, the module will be stopped and the screen refreshed to reveal the new state of the ActiveMQ module, as shown in Figure 16-3.

Image from book
Figure 16-3: A listing of the system modules with the ActiveMQ module in a stopped state

Notice the change in state for the ActiveMQ module. To start it up again, simply click the link named Start and the screen will be refreshed to again match that of Figure 16-2.

Managing ActiveMQ from the Geronimo Console

The Geronimo console has a surprising amount of functionality. One of the features within the console is the capability to add network connectors (or JMS network listeners). Figure 16-4 displays the network listeners available to be created from within the JMS Server screen.

Image from book
Figure 16-4: The JMS Server screen provides the ability to manage network listeners within ActiveMQ

For example, to add a jabber network listener, simply click on the peer link and fill in the form. Figure 16-5 shows an example of this.

Image from book
Figure 16-5: Adding a jabber network listener

Ensure that you give the network listener a unique name and port number so that it doesn’t clash with one that is already deployed within Geronimo. After you add the peer network listener, it is made available for use within Geronimo. Adding other types of network listeners is the same as this example but will use whatever protocol is selected.


The ActiveMQ Resource Adapter

The ActiveMQ resource adapter is a J2EE Connector Architecture 1.5 (JCA) compliant adapter. JCA provides an independent and standardized mechanism for integrating with systems external to an application server via a standard set of contracts. JCA defines contracts for the management of lifecycle, connections, transactions, security, work, message inflow, and transaction inflow. Apache Geronimo supports JCA 1.5 and utilizes it to provide JMS resources and JDBC connection pooling. Through the use of a JCA resource adapter descriptor, the JMS resources will be packaged in a Resource Adapter Archive (RAR) and deployed into the Geronimo server.

You can think of the resource adapter as a driver for the ActiveMQ broker. It is common to change the composition of the ActiveMQ resource adapter by changing its configuration. Different situations call for different connection factories and/or destinations. This section explains the ActiveMQ resource adapter configuration.

JMS Resources

JMS resources include connection factories and destinations. In JMS parlance, these are known as administered objects. Administered objects are typically available from a JNDI environment naming context (ENC) and are vital for a message broker because they’re for use by JMS clients.

Connection Factories

Connection factories are used to create connections to and sessions for a JMS provider. These connections can be created either for queues or topics, and provide the capability to require authentication. Connections can also be used to create JMS sessions.

Sessions

Sessions are used to create message producers and consumers for particular destinations and have the capability to be transaction bound.

Destinations

Destination objects are used by JMS clients to send and receive messages. There are two standard types of destinations: a queue and a topic. Queues are used by the point-to-point messaging paradigm, while topics are used by the publish-subscribe messaging paradigm.

J2EE Connector Architecture and JMS Resources

The RAR file mentioned earlier is packaged using the jar tool and must include a deployment descriptor in a META-INF directory, as well as any additional necessary elements (such as Java classes, native libraries, and any documentation and images). These contents are broken down in Table 16-2.

Table 16-2: The RAR File Contents Open table as spreadsheet
Item | Required | Location
Deployment Descriptor | Yes | META-INF/ra.xml
Documentation | No | Arbitrary
Dependent Classes | No | Arbitrary
Native Libraries | No | Arbitrary

The deployment of these resources takes place via the resource adapter deployment descriptor and the repository/geronimo/activemq-rar/1.1/activemq-rar-1.1.rar file. The contents of this RAR file are shown in Listing 16-2.

Listing 16-2: The Contents of the activemq-rar-1.1.rar File
Image from book

META-INF/
META-INF/MANIFEST.MF
META-INF/ra.xml
activemq-core-3.2.4.jar
activemq-ra-3.2.4.jar
META-INF/LICENSE.txt
Image from book

The main item in the activemq-rar-1.1.rar file is the activemq-ra-3.2.4.jar file. This is a JCA resource adapter from the ActiveMQ project, so it’s not specific to only Geronimo. This component facilitates integration between any J2EE 1.4 container and the ActiveMQ message broker to control transactions, manage security, and pool connections.


ActiveMQ Resource Adapter Configuration

When the need arises to deploy JMS resources, those resources can be deployed using either the Geronimo deployer or the Geronimo Web console. For more information on the Geronimo deployer, see Chapter 6. The deployer functionality (as it relates to deploying JMS resources) is discussed here. For demonstration purposes, the examples provided follow the default ActiveMQ resource adapter plan as a base.

The ActiveMQ plan has a dependency on the ActiveMQ message broker plan and can only be successfully deployed if that plan is already deployed. Only once the ActiveMQ broker is deployed can the ActiveMQ plan be deployed. So, let’s walk through the independent deployment of the ActiveMQ resource adapter and some JMS resources that use it.

Because the deployment plan is the only requirement for a RAR file, understanding it is critical to understanding the configuration and deployment of JMS resources for the message broker. The following configuration tells Geronimo to make the JMS resources available via the resource adapter. Listing 16-3 shows the deployment plan.

Listing 16-3: The ActiveMQ Resource Adapter Deployment Plan
Image from book
<?xml version="1.0" encoding="UTF-8"?>
<connector xmlns="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1">
  <dep:environment xmlns:dep="http://geronimo.apache.org/xml/ns/deployment-1.1">
    <dep:moduleId>
      <dep:groupId>geronimo</dep:groupId>
      <dep:artifactId>activemq</dep:artifactId>
      <dep:version>1.1</dep:version>
      <dep:type>car</dep:type>
    </dep:moduleId>
    <dep:dependencies>
      <dep:dependency>
        <dep:groupId>geronimo</dep:groupId>
        <dep:artifactId>activemq-broker</dep:artifactId>
        <dep:type>car</dep:type>
      </dep:dependency>
    </dep:dependencies>
    <dep:hidden-classes/>
    <dep:non-overridable-classes/>
  </dep:environment>
  <resourceadapter>
    <resourceadapter-instance>
      <resourceadapter-name>ActiveMQ RA</resourceadapter-name>
      <config-property-setting name="ServerUrl">tcp://localhost:61616</config-
property-setting>
      <config-property-setting name="UserName">geronimo</config-property-setting>
      <config-property-setting name="Password">geronimo</config-property-setting>
      <workmanager>
        <gbean-link>DefaultWorkManager</gbean-link>
      </workmanager>
    </resourceadapter-instance>
    <outbound-resourceadapter>
      <connection-definition>
        <connectionfactory
interface>javax.jms.ConnectionFactory</connectionfactory-interface>
        <connectiondefinition-instance>
          <name>DefaultActiveMQConnectionFactory</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>
              <blocking-timeout-milliseconds>5000</blocking-timeout-milliseconds>
              <match-one/>
            </single-pool>
          </connectionmanager>
        </connectiondefinition-instance>
      </connection-definition>
    </outbound-resourceadapter>
  </resourceadapter>
  <adminobject>
    <adminobject-interface>javax.jms.Queue</adminobject-interface>
    <adminobject-class>org.codehaus.activemq.message.ActiveMQQueue</adminobject-
class>
    <adminobject-instance>
      <message-destination-name>MDBTransferBeanOutQueue</message-destination-name>
      <config-property-setting name="PhysicalName">MDBTransferBeanOutQueue</config-
property-setting>
    </adminobject-instance>
  </adminobject>
  <adminobject>
    <adminobject-interface>javax.jms.Queue</adminobject-interface>
    <adminobject-class>org.codehaus.activemq.message.ActiveMQQueue</adminobject-
class>
    <adminobject-instance>
      <message-destination-name>SendReceiveQueue</message-destination-name>
      <config-property-setting name="PhysicalName">SendReceiveQueue</config-
property-setting>
    </adminobject-instance>
  </adminobject>
</connector>
Image from book

The contents of Listing 16-3 are fairly complex, but walking through it one element at a time makes it easier to understand. Tables 16-3 and 16-4 contain descriptions of the allowed contents of a resource adapter deployment plan. Table 16-3 contains a description of the actual contents in the plan displayed in Listing 16-3.

Table 16-3: Allowed Content of a Resource Adapter Plan Open table as spreadsheet
Item | Description
environment | An encapsulating root element for the module plan file.
connector | The root element of the deployment descriptor for the resource adapter. This element includes general information and also includes information specific to the implementation of the resource adapter library as specified through the element resourceadapter.
moduleId | The unique identifier for the descriptor.
dependencies | Holds all the dependency information.
hidden-classes | A list of classes that will never be loaded from parent class loaders of this module. The classes are specified in zero or more child filter elements, where each filter element specifies a fully qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed here will be treated as hidden.
non-overridable-classes | A list of classes that will only be loaded from parent class loaders of this module (never from the module’s own class loader). Just as with the hidden-classes element, the classes are specified in zero or more child filter elements where each filter element specifies a fully qualified class name or prefix. Essentially, any class that starts with one of the prefixes listed here will be treated as hidden.
resourceadapter | A container element holding the resourceadapter-instance and outbound-resourceadapter elements.
workmanager | A container element holding one of gbean-link, target-name, or a group of elements including domain, server, application, module, type, and name. The work manager handles work on behalf of the resource adapter in a parallel-processing manner.
resourceadapter-instance | A container element to hold the necessary information about the resource adapter and its configuration.
resourceadapter-name | A simple name for the resource adapter.
outbound-resourceadapter | Specifies information about an outbound resource adapter, including fully qualified names of classes and interfaces required as part of the connector architecture-specified contracts for connection management, level of transaction support provided, one or more authentication mechanisms supported, and additional required security permissions.
connection-definition | A container element holding information about a connection that implements a particular interface.
connectionfactoryinterface | The fully qualified package path to the implemented interface.
connectiondefinitioninstance | Additional interfaces implemented by the connection factory, used by the application.
implemented-interface | The actual interface that the implementation covers.
connectionmanager | The configuration of the connection manager.
container-managed-security | A wrapper element containing information to customize the container-managed security.
no-transaction | An empty marker element indicating that the resource adapter does not participate in transactions.
local-transaction | An element indicating that the resource adapter can participate in local transactions only.
xa-transaction | An element indicating that the resource adapter can participate in distributed transactions.
transaction-caching | An element that allows resources to be shared during the duration of the transaction. This is dependent upon whether the resource has been marked as shareable.
thread-caching | An element that allows the sharing of a single connection across transactions.
transaction-log | An element that allows a local JDBC resource to be able to participate in XA transactions
no-pool | Indicates that no connection pool should be used (that is, each request will cause a new connection to be established).
single-pool | Indicates that a single connection pool should be used.
match-one | This element indicates that the first connection acquired from the pool should be tested for validity against the pooling criteria.
match-all | This element indicates that all connection acquired from the pool should be tested for validity against the pooling criteria.
select-one-assume-match | This element indicates that no connections acquired from the pool should be tested.
partitioned-pool | Indicates that a partitioned connection pool should be used. Partitioned connection pools are segregated into many single pools, using one of the following marker subelements: partition-by-subject or partition-by-connection requestinfo.
partition-by-subject | An element to indicate that one partition per subject should be used.
partition-by-connectionrequestinfo | An element indicating that one partition per set of connection request information should be used.
max-size | The maximum number of connection in a single pool or a partitioned pool. Once this size is reached, requests will begin to block until a connection becomes available. The default is 10.
min-size | The minimum number of connection in a single pool or a partitioned pool. The default is zero.
blocking-timeoutmilliseconds | This element indicates the timeout period when waiting for a connection to be returned from a pool when all connections in a pool are in use and the pool has already reached its max-size. The default is 5000 milliseconds.
idle-timeout-minutes | The amount of time a connection is allowed to go unused before it is automatically closed. The default is 15 minutes.
adminobject | Specifies information about an administered object. Administered objects are specific to a messaging style or message provider. This contains information on the Java type of the interface implemented by an administered object, its Java class name, and its configuration properties.
adminobject-interface | The interface implemented by the adminobject-class element.
adminobject-class | The implementation class of the adminobject-interface element.
adminobject-instance | A container element holding the configuration information for this adminobject element.
message-destination-name | A unique name for the adminobject to be used for the JNDI ENC.
config-property-setting | Contains an arbitrary name/value pair for configuration of the adminobject.
gbean | An element for describing GBeans within the resource adapter.
Table 16-4: Breakdown of the Contents of the ActiveMQ Resource Adapter Open table as spreadsheet
Item | Description
geronimo/activemq/1.1/car | This is the unique ID that is generated by flattening the contents of the moduleId element. This string doesn’t reside in ra.xml, but is used to uniquely identify it throughout Geronimo.
<dependencies> | The necessary dependencies for the ActiveMQ resource adapter configuration.
ActiveMQ RA | A simple string name for the resource adapter.
DefaultWorkManager | This is a reference to the DefaultWorkManager GBean, which is located in the j2ee-server deployment plan.
javax.jms.ConnectionFactory | The fully qualified package name of the interface used by the connection factory.
DefaultActiveMQ ConnectionFactory | This item is responsible for creating both queue connections and topic connections, hence the reference to the implemented interfaces javax.jms.QueueConnectionFactory and javax.jms.TopicConnectionFactory.
<connectionmanager> | The connection manager is responsible for handling the JMS connections. The elements contained herein tell the connection manager to participate in distributed transactions, to share connections among components, and to maintain a single connection pool whose maximum size is 10 connections with a blocking timeout of 5000 milliseconds to wait for any connection to become available.
MDBTransferBeanOutQueue | This is an adminobject for a JMS queue named MDBTransfer BeanOutQueue that exposes the javax.jms.Queue via the org.codehaus.activemq.message.ActiveMQQueue class.
SendReceiveQueue | This is an adminobject for a JMS queue named SendReceiveQueue that also exposes the javax.jms.Queue via the org.codehaus.activemq.message.ActiveMQQueue class.

This list covers the geronimo-connector-1.1 schema, but not the connector-1.5 schema, so it’s not 100 percent exhaustive. Again, the ActiveMQ resource adapter configuration serves the RAR file and is utilized by the Geronimo deployer upon deployment. Now that the allowed content of a resource adapter deployment plan has been discussed, the content of the instance in Listing 16-3 should be explored, as shown in Table 16-4.

Tables 16-3 and 16-4 document not only the allowed content of the Geronimo resource adapter plan (Table 16-3), but also the actual content of the plan (see Table 16-4). The allowed content of the plan actually is the configuration for the resource adapter. The next step is the deployment of these resources to the Geronimo server.

Deploying JMS Resources

When the Geronimo server starts up, the ActiveMQ message broker is started. In addition, some administered objects and a couple of JMS queues are deployed as well. These queues are dependent upon the ActiveMQ broker and are deployed using the Geronimo deployer as demonstrated here. But these queues are present in the ActiveMQ resource adapter plan. As noted earlier in this chapter, the plan files are not distributed with the Geronimo binaries. They are only available in the Geronimo source code.

There are two ways to deploy JMS resources:

  • Via the command line

  • Via the Geronimo Web console

Deploying Via the Command Line

Using the Geronimo deployer to deploy JMS resources via the command line can be accomplished through the use of the deployment plan for the ActiveMQ resource adapter.

Listing 16-4 shows the addition to the plan.

Listing 16-4: Adding a New JMS Topic to the Plan
Image from book
<adminobject>
    <adminobject-interface>javax.jms.Topic</adminobject-interface>
    <adminobject-class>
        org.codehaus.activemq.message.ActiveMQTopic
    </adminobject-class>
    <adminobject-instance>
        <message-destination-name>ProGeronimoTopic</message-destination-name>
        <config-property-setting name="PhysicalName">
            ProGeronimoTopic
        </config-property-setting>
    </adminobject-instance>
</adminobject>
Image from book

This chunk of XML simply tells the ActiveMQ resource adapter to set up a JMS topic whose name is ProGeronimoTopic. To deploy this plan, the following command will be used:

$ ./bin/deploy.sh --user system --password manager deploy /path/to/plan.xml
repository/geronimo/activemq-rar/1.1/activemq-rar-1.1.rar
Using GERONIMO_BASE:   /Users/bsnyder/geronimo-1.1
Using GERONIMO_HOME:   /Users/bsnyder/geronimo-1.1
Using GERONIMO_TMPDIR: /Users/bsnyder/geronimo-1.1/var/temp
Using JRE_HOME:
/System/Library/Frameworks/JavaVM.framework/Versions/1.4/Home
    Deployed geronimo/activemq/1.1/car

Notice that this command includes not only the plan that was changed but also the ActiveMQ resource adapter archive. The reason for this is that the plan is a JCA resource adapter deployment descriptor. JMS resources are deployed using a resource adapter because that is the contract for communication between a J2EE server and a message broker. Upon executing the previous command, the following log messages will appear in the var/log/geronimo.log file:

19:20:11,617 DEBUG [GBeanInstanceState] GBeanInstanceState for:
geronimo.server:J2EEApplication=null,J2EEServer=geronimo,JCAResource=org/apache/ger
onimo/SystemJMS,j2eeType=JCAAdminObject,name=ProGeronimoTopic State changed from
stopped to starting
19:20:11,640 DEBUG [GBeanInstanceState] GBeanInstanceState for:
geronimo.server:J2EEApplication=null,J2EEServer=geronimo,JCAResource=org/apache/ger
onimo/SystemJMS,j2eeType=JCAAdminObject,name=ProGeronimoTopic State changed from
starting to running

These messages indicate changes of state in the topic named ProGeronimoTopic that was added to the plan. The result is the deployment of the new JMS topic.

Another manner in which to verify that this resource is truly deployed is to verify it in the Geronimo Console. Figure 16-6 shows the console while viewing the JMS service.

Image from book
Figure 16-6: Verifying that the ProGeronimoTopic is deployed

Creating JMS Resource Groups in the Geronimo Console

The Geronimo console contains a concept known as JMS Resource Groups that are simply a grouping of JMS resources for deployment. A big benefit to working with JMS Resource Groups via the Web console is that it’s easier than working with a deployment plan and a RAR file directly. As shown in Figure 16-6, JMS Resources are listed in the Web console in groups. Adding additional resources is a relatively simply task, which is demonstrated next.

Configure Server Connection

To create a new JMS Resource, click the link to add resources for ActiveMQ. Simply fill in the requested information in the form, as shown in Figure 16-7.

Image from book
Figure 16-7: Creating JMS Resources for ActiveMQ

Table 16-5 describes the available options within the initial JMS Resource creation screen from Figure 16-7.

Table 16-5: Available Options When Creating a JMS Resource Group Open table as spreadsheet
Item | Description
Resource Group Name | A unique name to identify the resource group in the Web console and to applications that intend to use the resource group.
ServerURL | The URL on which the ActiveMQ message broker has been made available.
UserName | The default username for accessing ActiveMQ within Geronimo is simply geronimo.
Password | The default password for accessing ActiveMQ within Geronimo is simply geronimo.
Clientid | A unique ID for identification of clients connecting to ActiveMQ. This is not required, so it is left blank.
UseEmbededBroker | A Boolean value indicating the start of a new ActiveMQ instance. This is usually set to false because there is already an ActiveMQ instance running.
UseInboundSession | This Boolean value determines whether a single connection should be shared for the inbound and outbound communications with the resource adapter.
BrokerXmlConfig | The configuration file to use for the message broker configuration. If a full URL is not provided, it is assumed the file lives on the classpath.

Click the Next button and the screen in Figure 16-8 appears, presenting the option of creating either a connection factory or a destination.

Image from book
Figure 16-8: Create either a connection factory or a destination

Selecting the Connection Factory Type

Upon clicking the button to create a connection factory, the screen in Figure 16-9 is displayed, requesting information for the connection factory.

Image from book
Figure 16-9: Determine the type of connection factory to create

This screen offers the ability to choose the type of connection factory to create. Available choices include the following:

  • javax.jmx.ConnectionFactory - Used to create a connection with the ActiveMQ message broker.

  • javax.jms.QueueConnectionFactory - Used to create a point-to-point QueueConnection with the ActiveMQ message broker.

  • javax.jms.TopicConnectionFactory - Used to create a publish/subscribe TopicConnection with the ActiveMQ message broker.

Simply choose a connection factory type, and click the Next button.

Configure Connection Factory

It’s now time to configure the connection factory. Figure 16-10 shows the screen that should be displayed now. Table 16-6 describes the fields.

Image from book
Figure 16-10: Fill in the necessary metadata for the connection factory
Table 16-6: Available Options When Configuring the Connection Factory Open table as spreadsheet
Item | Description
Connection Factory Name | A unique name to identify the connection factory in the Web console and to applications that intend to use the resource group.
Transaction Support | Choose the type of transactions in which this connection factory should participate.
Pool Min Size | The minimum size for the connection pool. The default is zero.
Pool Max Size | The maximum size for the connection pool. Once the pool reaches this size, requests for connections will begin to block using the Blocking Timeout waiting for available connections. The default is 10.
Blocking Timeout | The duration of time for which requests will be blocked waiting for available connections. The default is 5000 milliseconds.
Idle Timeout | The amount of time a connection is allowed to go unused before it is automatically closed. The default is 15 minutes.

Simply fill in the form, and click the Next button to see the Current Progress screen.

Current Progress

The Current Progress screen is now displayed, as shown in Figure 16-11.

Image from book
Figure 16-11: The connection factory has been created

This screen demonstrates that the connection factory named ProGeronimoConnectionFactory has been created, but there are no destinations available yet. The next step is to click the Add Destination button to create one.

Select Destination Type

The Select Destination Type screen provides the ability to choose the type of destination to create, as shown in Figure 16-12.

Image from book
Figure 16-12: Adding a JMS queue

The two destination types available include the following:

  • javax.jms.Queue - Provides point-to-point-style messaging that provides messaging in a one-to-one or many-to-one paradigm.

  • javax.jms.Topic - Provides publish/subscribe-style messaging that provides messaging in a many-to-many paradigm.

Once the destination type has been selected, it must be configured.

Configure Destination

Adding a destination is very simple as shown by Figure 16-13. Table 16-7 shows the options on this screen.

Image from book
Figure 16-13: Naming the queue
Table 16-7: Configuring the Destination Open table as spreadsheet
Item | Description
Message Destination Name | A unique name to identify this destination in the Web console and to applications that intend to use the destination.
Physical Name | This name can be used to map this destination to a different destination in the message broker. This use case is fairly rare, and providing the same name as the Message Destination Name is very common.

Click the Next button to proceed to the progress screen again to see what has been added to the ProGeronimo JMS Resource Group.

Current Progress Again

So far, a connection factory and a destination have been added to the ProGeronimo JMS Resource Group, as shown in Figure 16-14.

Image from book
Figure 16-14: The JMS queue has been created

To see the XML plan that is created by this whole process, click the Show Plan button.

Show Deployment Plan

The Deployment Plan text area shows the XML plan resulting from the process of creating the ProGeronimo JMS Resource Group, as shown in Figure 16-15.

Image from book
Figure 16-15: Viewing the plan

As Figure 16-15 indicates, this XML plan can be copied, saved to a file, and deployed using the command-line deployer. But why go to that trouble when there is a button right there named Deploy JMS Resource? One answer is that there may be a reason to check this XML plan into a version-control system for tracking and further development. Another reason might be that there may be a policy to deploy from the command line within an IT department across a farm of servers. The point is that the user is given a choice. However, if the Deploy JMS Resource button is clicked, the JMS Resource is deployed, and the Available JMS Resources screen appears, showing something new.

Available JMS Resources

The listing of available JMS Resources now has a new resource named ProGeronimo, as shown in Figure 16-16.

Image from book
Figure 16-16: The ProGeronimo JMS Resource Group deployed

This resource contains the ProGeronimoConnectionFactory and the ProGeronimoQueue, which are both available for use now.


Deployment Scope

There are three scopes of deployment within Geronimo:

  • Serverwide

  • Application scope

  • Client scope

This relates to the ability to configure resources at the server level, the server-side application level and the client-side application level.

The serverwide scope is what has been demonstrated in this chapter. Resources deployed with the serverwide scope are available for use by any application. That is, serverwide scoped resources can be used by other serverwide-scoped resources as well as by other server-side applications but not client-side applications by default.

Application level and client level scoping are concerns for developers and J2EE module assemblers. In these scenarios, the resource adapter is configured within the application and not shared by other applications running on the server.


Summary

ActiveMQ is a robust, scalable message broker that is integrated into Geronimo. The default configuration for ActiveMQ is usually sufficient for development but will most likely need some tuning to move into production. This chapter covered some high-level information about the features offered by ActiveMQ, and a bit about its architecture.

The integration of the ActiveMQ message broker within Geronimo and how to customize the message broker configuration were shown, as well as the configuration of JMS resources within Geronimo. Discussions and demonstrations of the Geronimo console were covered throughout the chapter as an easier mechanism for administration and customization than working with XML all the time.


Appendix A: Geronimo Deployment Plans Cross-Reference

Overview

This section provides a reference of the Geronimo specific deployment plans for:

  • Web-tier components and applications

  • Business-tier Enterprise JavaBeans (EJBs)

  • Enterprise applications

  • JCA connectors (such as JDBC drivers and JMS Connection factories)

  • Client applications using the Geronimo application client container

The location of each deployment plan is first tabulated. Next, the reference namespace used by the elements in the file is shown. Then the top-level elements in each plan are explained. In the description, the location of the XML schema file (XSD) is also provided. Specific references to book chapters for more detailed usage information and deployment example are provided where applicable in the description. This reference section should be useful when you fabricate your own Geronimo-specific deployment plans.

Table A-1 shows the five Geronimo deployment plans discussed in this appendix.

Table A-1: Geronimo-Specific Deployment Plans in This Appendix Open table as spreadsheet
Plan | Description
geronimo-web.xml | For the deployment of Web application incorporating JSP and servlets. The deployed module is archived in a WAR file.
openejb-jar.xml | For the deployment of EJBs in their own JAR files. The deployed module is an EJB JAR file.
geronimo-application.xml | For the deployment of Enterprise applications, potentially including Web-tier WAR, business-tier EJB JAR, and JCA con-nectors for Enterprise Integration Services (EIS) tier servers. The deployed module is an EAR file.
geronimo-ra.xml | For the deployment of JCA connectors. These are typically JDBC connectors, or resource adapters for message queue bro-kers. The deployed module is a JAR archive.
geronimo-client.xml | For the deployment of a J2EE client application that uses the Geronimo application client container. The deployed module is a client application JAR file.


Deploying Web-Tier Applications - geronimo-web.xml

The geronimo-web.xml deployment plan is used to deploy a Web-tier application (consisting of JSP and servlets coding, to Geronimo). Table A-2 shows the location of this deployment plan and the associated XML schema.

Table A-2: Location and Name of XML Schema for Web-Tier Application Deployment plan Open table as spreadsheet
Expected location of deployment plan, if included in the deployed module | In the WEB-INF subdirectory of the WAR file
Location of XML schema (XSD) | Source code distribution, schema
Name of XML schema | geronimo-web-1.1.xsd

Reference Namespaces

The namespaces to use in this file are the attributes of the top-level <web-app> element:

<web-app   xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.1"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
    xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1">
...

Top-Level Elements

Table A-3 contains descriptions of top-level elements in the geronimo-web.xml Geronimo-specific deployment plan.

Table A-3: Top-Level Elements of geronimo-web.xml Open table as spreadsheet
Element | Description
<sys:environment> | Specifies the module ID and dependencies in this element via <moduleId> and <dependencies> elements. You can also use module class-loading control elements such as <hidden-classes> to specify classes that are hidden from parent class loaders; <non-overridable- classes> to specify classes that are only loaded from parent class loaders; or <inverse-classloading> to specify that standard classloader delegation should be reversed. Inheritance of environment by module can be suppressed using <suppress-default-environment>.
<context-root> | Specifies a context path to the deployed application. This context path appears in the URL used to address the application on a Geronimo server. By default, the application deploy module base name (without the extension) is used. Typically, this element is used in a WAR deployment.
<naming:web-container> | Reference a web-container-specific GBean either by pattern or via a link to the GBean.
<container-config> | This element is reserved for the configuration of elements specific to the underlying Web-tier container. In Geronimo’s case, this is either Jetty or Tomcat. See Chapters 11 and 12 for application of this element.
JNDI Environment References | See comment immediately following this table.
<naming:message-destination> | References a message-destination (such as JMS queues), which is used within the deployed WAR file.
<security-realm-name> | Specifies the name of the security realm that will be used for user authentication.
<security:security> | Configures the security role mappings that will be used when deploying the module. Maps roles specified in the WAR file to roles or principals in the security realm. See Chapter 16 for more information on the use of this element.
<sys:gbean> | Specifies additional GBeans that are configured and deployed with this module.

JNDI Environment References refers to container managed JNDI resources and can be one or more of:

<ejb-ref>, <ejb-local-ref>, <resource-ref>, <resource-enf-ref>, <service-ref>, or <gbean-ref>.


Deploying Business-Tier EJBs - openejb-jar.xml

This openejb-jar.xml deployment plan is used to deploy a collection of business-tier EJBs in an EJB JAR file. Table A-4 shows the location of this deployment plan and the associated XML schema.

Table A-4: Location and Name of XML Schema for Business-Tier EJB JAR Deployment Plan Open table as spreadsheet
Expected location of deployment plan, if included in the archive | In the META-INF subdirectory of the JAR file
Location of XML schema (XSD) | Source code distribution, schema directory
Name of XML schema | openejb-jar-2.1.xsd

Reference Namespaces

The namespaces to use in this file are the attributes of the top-level <openejb-jar> element:

<openejb-jar  xmlns=" http://www.openejb.org/xml/ns/openejb-jar-2.1"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
    xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1"
    xmlns:pkgen="http://www.openejb.org/xml/ns/pkgen-2.0">
...

Top-Level Elements

Table A-5 contains descriptions of top-level elements in the openejb-jar.xml Geronimo-specific deployment plan.

Table A-5: Top-Level Elements of openejb-jar.xml Open table as spreadsheet
Element | Description
<sys:environment> | Specifies the module ID and dependencies in this element via <moduleId> and <dependencies> element. You can also use module class-loading control elements such as <hidden-classes> to specify classes that are hidden from parent class loaders; <non- overridable-classes> to specify classes that are only loaded from parent class loaders; or <inverse- classloading> to specify that standard class loader delegation should be reversed. Inheritance of environment by module can be suppressed using <suppress-default-environment>.
<naming:cmp-connection-factory> | Specifies a database pool to be used by Container Managed Persistence (CMP).
<ejb-ql-compiler-factory> | Specifies by name a Java class that can compile EJB QL (Query Language) to SQL statements for execution on CMP EJBs.
<db-syntax-factory> | Specifies by name a Java class that can map to the SQL syntax of a specific database. Used in CMP to adapt to different vendor’s RDBMS products.
<enforce-foreign-key-constraints> | Determines if the container will attempt to enforce foreign key constraints during database operations. This should be specified only when the RDBMS used support foreign key integrity constraints.
<enterprise-beans> | Specifies the resources referenced by <session> and <entity> EJBs. Used mainly for J2EE 1.3 compatibility and reference resources (such as JMS destinations) that are not available with 1.3 descriptors.
<relationships> | Specifies relationships between EJBs (one-to-one, one-to-many, many-to-many) and Container Managed Relationship (CMR) fields.
<naming:message-destination> | References a message-destination (such as JMS queues), which is used within the deployed WAR file.
<security:security> | Configures the security role mappings that will be used when deploying the module. Maps roles specified in the plan to roles or principals in the security realm. See Chapter 16 for more information on the use of this element.
<sys:gbean> | Specifies additional GBeans that are configured and deployed with this module.


Deploying EIS-Tier JCA connectors - geronimo-ra.xml

This geronimo-ra.xml deployment plan is used to deploy a resource adapter (JCA 1.5 connector) in an JAR file. Table A-6 shows the location of this deployment plan and the associated XML schema.

Table A-6: Location and Name of XML Schema for EIS-Tier Resource Adapter JAR Deployment Plan Open table as spreadsheet
Expected location of deployment plan, if included in the archive | In the META-INF subdirectory of the resource adapter JAR file
Location of XML schema (XSD) | Source code distribution, schema directory
Name of XML schema | geronimo-connector-1.1.xsd

Reference Namespaces

The namespaces to use in this file are the attributes of the top-level <connector> element:

<connector  xmlns ="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1">
...

Top-Level Elements

Table A-7 contains descriptions of top-level elements in the geronimo-ra.xml Geronimo-specific deployment plan.

geronimo-ra.xml
Table A-7: Top-Level Elements of geronimo-ra.xml Open table as spreadsheet
Element | Description
<sys:environment> | Specifies the module ID and dependencies in this element via <moduleId> and <dependencies> element. You can also use module class-loading control elements such as <hidden-classes> to specify classes that are hidden from parent class loaders; <non-overridable-classes> to specify classes that are only loaded from parent class loaders; or <inverse-classloading> to specify that standard class loader delegation should be reversed. Inheritance of environment by module can be suppressed using <suppress-default- environment>.
<resourceadapter> | Element that describes the JCA adapter - such as a JDBC connector or JMS connection factory.
<adminobject> | See description in Table A-8.
<sys:gbean> | Specifies additional GBeans that are configured and deployed with this module.

An admin object in JCA is usually a configured JMS topic or queue. An admin object has a <message- destination-name> in its <adminobject-instance> and can be referred to in other plans via the <naming:message-destination> reference element. Table A-8 shows the subelements of an <adminobject> element.

Table A-8: The <adminobject> Element Open table as spreadsheet
Element | Description
<adminobject-interface> | The interface that the admin object implements (for example, javax.jms.Topic)
<adminobject-class> | The Java class of the admin object
<adminobject-instance> | <message-destination-name> for external reference and <config-property-setting>


Deploying Enterprise Applications - geronimo-application.xml

This geronimo-application.xml deployment plan is used to deploy an enterprise application containing Web application WAR(s), EJB JAR(s), client application JAR(s), and JCA connector JAR(s). Table A-9 shows the location of this deployment plan and the associated XML schema.

Table A-9: Location and Name of XML Schema for the Enterprise Application Deployment Plan Open table as spreadsheet
Expected location of deployment plan, if included in the archive | In the META-INF subdirectory of the EAR file
Location of XML schema (XSD) | Source code distribution, schema directory
Name of XML schema | geronimo-application-1.1.xsd

Reference Namespaces

The namespaces to use in this file are the attributes of the top-level <application> element:

<application xmlns ="http://geronimo.apache.org/xml/ns/j2ee/application-1.1"
    targetNamespace="http://geronimo.apache.org/xml/ns/j2ee/application-1.1"
    xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1">
...

Top-Level Elements

Table A-10 contains descriptions of top-level elements in the geronimo-application.xml Geronimo-specific deployment plan.

Table A-10: Top-Level Elements of geronimo-application-client.xml Open table as spreadsheet
Element | Description
<sys:environment> | Specifies the module ID and dependencies in this element via <moduleId> and <dependencies> element. You can also use module class-loading control elements such as <hidden-classes> to specify classes that are hidden from parent class loaders; <non-overridable-classes> to specify classes that are only loaded from parent class loaders; or <inverse-classloading> to specify that standard class loader delegation should be reversed. Inheritance of environment by module can be suppressed using <suppress-default-environment>.
<module> | One or more <module> elements define the modules that will be deployed in this application. Each module optionally includes a Geronimo-specific deployment plan in an <alt-dd> element.
<ext-module> | Refers to an external module that is being deployed or redeployed. It can refer to, and be used in the configuration of a module that is already in the local repository.
<security:security> | Configures the security role mappings that will be used when deploying the module. Maps roles specified in the plan to roles or principals in the security realm. See Chapter 16 for more information on the use of this element.
<sys:gbean> | Specifies additional GBeans that are configured and deployed with this module.


Deploying J2EE Application Clients - geronimo-application-client.xml

This geronimo-application-client.xml deployment plan is used to deploy a J2EE application client that uses the Geronimo client application container. The client is bundled in an application JAR, potentially inside an enterprise application EAR. Table A-11 shows the location of this deployment plan and the associated XML schema.

Table A-11: Location and Name of XML Schema for the Application Client Deployment Plan Open table as spreadsheet
Expected location of deployment plan, if included in the archive JAR file | In the META-INF subdirectory of the client application
Location of XML schema (XSD) | Source code distribution, schema directory
Name of XML schema | geronimo-application-client-1.1.xsd

Reference Namespaces

The namespaces to use in this file are the attributes of the top-level <application-client> element:

<application-client   xmlns="http://geronimo.apache.org/xml/ns/j2ee/application-
client-1.1"
    xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.1"
    xmlns:connector="http://geronimo.apache.org/xml/ns/j2ee/connector-1.1"
    xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
    xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.1">
...

Table A-12 provides descriptions of top-level elements in the geronimo-application-client.xml Geronimo-specific deployment plan.

Table A-12: Top-Level Elements of geronimo-application-client.xml Open table as spreadsheet
Element | Description
<sys:client-environment> | Specifies the module ID and dependencies in this element via <moduleId> and <dependencies> element. You can also use module class-loading control elements such as <hidden-classes> to specify classes that are hidden from parent class loaders; <non-overridable-classes> to specify classes that are only loaded from parent class loaders; or <inverse-classloading> to specify that standard class loader delegation should be reversed. Inheritance of environment by module can be suppressed using <suppress-default- environment>. This specifies the environment for the client application JVM.
<sys:server-environment> | Similar to client-environment but specified for the server-side support module.
<naming:gbean-ref> | A GBean reference used by the client application to be resolved by the client container.
<naming:ejb-ref> | EJB referenced by the client application.
<naming:service-ref> | A Web service reference to be resolved by the client container.
<naming:resourceref> | A JNDI resource reference, typically to a JDBC connector, to be resolved by the client container.
<naming:resource-env-ref> | A resource-enf-ref to a JCA admin object, to be resolved by the client container.
<naming:message-destination> | References a message destination (such as JMS queues), that which is used by the client application to be resolved by the client container.
<realm-name> and/or <callback-handler> | Either a realm to use for authentication, and/or the <callback-handler>, which is a class that can be used to implement authentication.
<resource> | Reference to embedded resource internal to the client application JAR file. Typically a JCA connector either inside the JAR or already installed in the local repository.
<sys:gbean> | Specifies additional GBeans that are configured and deployed with this module.


J2EE Standard Specification Schemas for Deployment Descriptors

You can find the standard J2EE XML schemas used by Geronimo in the Geronimo Tomcat or Jetty distribution, under the schema subdirectory . You can find other XML DTDs and schemas for previous versions of J2EE (1.2, 1.3) in the same directory. These are provided because Geronimo is fully backward compatible.

Table A-13 provides the list of J2EE deployment descriptors associated with the deployable modules covered in this appendix.

Table A-13: XML Schemas of Standard J2EE Deployment Descriptor Open table as spreadsheet
Deployable Module | XML Schema for Deployment Descriptor
Web application in a WAR file. | web-app_2_4.xsd web-app_2_3.dtd web-app_2_3.dtd
Enterprise JavaBeans in an EJB JAR file. | ejb-jar_2_1.xsd ejb-jar_1_1.dtd ejb-jar_2_0.dtd
JCA connector in a JAR file. | connector_1_5.xsd connector_1_0.xsd connector_1_0.dtd
Enterprise application in an EAR file. | application_1_4.xsd application_1_3.dtd application_1_2.dtd
Client application in a JAR file. | application-client_1_4.xsd application-client_1_3.dtd application-client_1_2.dtd


Appendix B: Run-Time Deployer Command Reference

Overview

J2EE deployable modules and Geronimo deployment plans can be installed on a Geronimo server instance using the run-time deployer. The run-time deployer can also be used to search a plug-in repository for available plug-ins and install any plug-in to provide new features to a Geronimo instance. The deployer usually executes when a target Geronimo instance is running. Some commands will also work offline locally, without a running instance of Geronimo. Online deployments can be performed locally (to a server running on the same machine) or remotely (to a Geronimo server running on another machine over the network).

The deployer can be used to do the following:

  • Deploy (install) a module or deployment plan

  • Redeploy a module or plan

  • Undeploy (uninstall) a configuration

  • Start a configuration

  • Stop a configuration

  • Save the required user login and password information during deployment

  • List all the running configurations

  • List available targets for deployment

  • Distribute a module to a target

  • Search for all plug-ins available from a plug-in repository or a running Geronimo instance

  • Install a plug-in bundle (CAR file)

All of these commands work against a running Geronimo server instance. If you must work with a local offline instance of Geronimo server, you can use the --offline option of the deployer.

The deployer is actually a JSR-88 client application, making use of Geronimo’s JSR-88 deployment plugins to do its work. Chapter 6 has a detailed discussion of the JSR-88 specification and its impact on J2EE server deployment and tool integration.

There are at least three ways to deploy a module and/or a plan in Geronimo:

  • Using the deployer

  • Use the Web console’s GUI interface

  • Use the hot deploy capabilities of Geronimo

This appendix provides a reference to the syntax of the deployer. It also provides instructions for the use of the GUI deployment interface and the hot deployer.


The Command-Line Deployer

The actual deployer is located in the following JAR file:

<geronimo installation dir>/bin/deployer.jar

To use this deployer, a Win32 batch script and *nix shell script is provided in the same directory:

  • deploy.bat

  • deploy.sh

For ease of use, this batch file or *nix shell script should be added to your PATH environment variable. Even without installing the deployer script file, however, the deployer can always be accessed via the following command issued from the <geronimo installation directory>:

java -jar bin/deployer.jar [options]  command [command options]

When using one of the script files, the command line is simplified to:

deploy [options]  command [command options]

Available Options

The options available for the deployer include the following:

  • --uri

  • --host

  • --port

  • --driver

  • --user

  • --password

  • --syserr

  • --verbose

  • --offline

Each of these options is described in the following sections.

The --uri Option

The URI to a Geronimo server instance is where the target for deployment resides. Deployed modules are sent to this server. If not specified, the default is the Geronimo server running on the local machine.

The general URI syntax, for Geronimo servers, is:

deployer:geronimo:jmx[://host[:port]]

For example, to see the modules running on a server running on 192.168.1.11, port 3030, use the following command:

deploy --uri deployer:geronimo:jmx://192.168.1.11:3030 list-modules

When this option is used, the --host or --port must not be specified. This option is an alternative to --host/--port when specifying a deployment Geronimo server instance.

The --host Option

This option is usually used in conjunction with --port. It specifies a Geronimo server instance, where the deployment will be performed.

When using the --host and --port options, you must not use the --uri option.

For example, to see the modules running on a server running on 192.168.1.11, port 3030, use the following command:

deploy --host 192.168.1.11  --port 3030 list-modules

The default is the local host.

The --port Option

This option is usually used in conjunction with --host option. It specifies the TCP port at which a Geronimo server instance listens to for deployment commands.

When using the --host and --port options, you must not use the --uri option.

See the preceding section, “The --host Option” for a usage example. The default port value is 1099. This is also the default port that a Geronimo instance will listen to for deployment commands.

The --driver Option

Since the deployer is actually a JSR-88–complaint client, it is capable of accepting other JSR-88 complaint server drivers. This should allow the deployer to be used with other non-Geronimo servers in the future.

The syntax is:

deploy --driver <path to JSR-88 plugin JAR>  list-modules

The default value is the Geronimo’s JSR-88 driver JAR.

The --user Option

This option specifies the username used in authentication with the server to gain deployment access on the target server. By default, the Geronimo server is configured with a geronimo-properties-realm security realm. This default realm contains a single user that has deployment access, called system.

In production, the deployer can be configured to allow deployment access only from specific authenticated users. An example usage (for the default configuration) is:

deploy --user system --password manager list-modules

The --password Option

Use this option in conjunction with the --user option to authenticate a user for deployment access to the target Geronimo instance. By default, the Geronimo server is configured with a geronimo- properties-realm security realm. This default realm contains one single user that has deployment access. This user is named system and has its password set to be manager.

See the preceding section, “The --user Option” for an example.

The --syserr Option

The option causes deployer logging to be displayed to the syserr stream. Typically, this is the same console where the deployment command is issued.

By default, no logging will be printed to the console.

The --verbose Option

Enabling this option causes the deployer to print detailed information to the console during its operation.

By default, the status output is relatively sparse and uncluttered. Use this option to troubleshoot deployment problems.

The --offline Option

Run the deployer on the local server without requiring a running instance of the Geronimo server locally. For example, to see the modules deployed on the local server, even when no Geronimo server is running, use the following command:

deploy --offline list-modules

Available Commands

The following sections describe the commands available with the deployer, as well as their associated command options.

The help Command

This is a handy command that can be used to display the options, commands, and command options that are available with the deployer. For general usage help, simply run the deployer with no options or commands:

deploy

To see all the options available, use the following command:

deploy help options

To see a description of any available command, use the following command:

deploy help <command>

For example, to get help on the deploy command, use the following from the command line:

deploy help deploy

The deploy Command

This is the primary command used to install a module, together with an optional plan, to a Geronimo server instance. The general syntax, with command options, is:

deploy deploy [--targets target1;target2;target 3;...]  [module] [plan]

The optional targets specification is a standard part of JSR-88, but it is not currently used by Geronimo. In the future, it may be used in scenarios where a Geronimo server can contain and manage multiple configuration stores.

The module is a J2EE deployable module, such as a WAR, EAR, JAR or RAR containing EJBs or JCA connectors, and so on. If the deployment descriptors included in the module are sufficient to deploy the module, there is no need to specify a plan. In the cases where a Geronimo-specific plan is already included in the module archive being deployed, there is also no need to specify a plan.

Note that when Geronimo-specific deployment plans are specified with the deploy command, the deployment plan can have any name. For example, if you specify a Geronimo-specific deployment plan for a WAR file during deployment, it does not have to be named geronimo-web.xml.

Occasionally, you may be deploying a module whose binaries are already uploaded to the Geronimo code repository. For example, you may be deploying a JDBC connector that is included in the Geronimo distribution. In these cases, the dependencies specified in the deployment plan refers to these predeployed modules, and there is no need to specify a module with the deploy command.

Once deployed, a module is identified by its module ID within Geronimo. This is a key concept since most of the other deployment commands work with module IDs.

The undeploy Command

This command stops a running module via the module ID and then uninstalls all the configuration information files and binaries from the server instance. The general syntax of this is command is as follows:

deploy undeploy <module ID> [<module ID> ....]

This command actually has a generalized JSR-88 syntax that specifies a TargetModuleID (instead of <module ID> shown in the syntax) that can include a target (cluster or host) identification. You specify this by using the following notation:

<target name>|<module ID/module name>

But this generalized syntax is not required by Geronimo at this time. Geronimo only supports a single target.

This command will remove the configuration from the config-store. The module cannot be started again, once undeployed, unless you use the deploy command again.

If the intention is to undeploy and then deploy again, this can be accomplished in one single step, using the redeploy command.

The redeploy Command

This command provides the following sequence of operations:

  1. Stops the specified configuration

  2. Undeploys the specified configuration from the server

  3. Deploys the specified module and/or plan to the server

  4. Starts the specified module

See the previous sections about the undeploy command, and the deploy command for more details on the deployment process. Note that the module is always started after this command.

The general command syntax is:

deploy redeploy [module] [plan] [<module ID> [<module ID> ....]]

This command actually has a generalized JSR-88 syntax that specifies a TargetModuleID (instead of <module ID> shown in the syntax) that can include a target (cluster or host) identification. You specify this by using the following notation:

<target name>|<module ID/module name>

But this generalized syntax is not required by Geronimo at this time. Geronimo only supports a single target.

With Geronimo, you will only specify a single <module ID>, if any, with this command.

If you do not specify the <module ID>, the plan supplied (or plan inside the module) will be used to determine the actual configuration that you wish to redeploy.

Redeploying a plan with an existing <module ID> allows you to modify the configuration of a running module without intermediate undeployment.

The start Command

This command starts module(s) running in the Geronimo server. The general syntax is:

deploy start [<module ID> [<module ID> ....]]

This command actually has a generalized JSR-88 syntax that specifies a TargetModuleID (instead of <module ID> in the syntax) that can include a target (cluster or host) identification. You specify this by using the following notation:

<target name>|<module ID/module name>

But this generalized syntax is not required by Geronimo at this time. Geronimo only supports a single target.

If you specify more than one <module ID>, Geronimo will attempt to start each one.

The <module ID> you specify must represent modules that are already deployed into the Geronimo server or system modules.

The stop Command

This command stops running configuration(s) in the Geronimo server. The general syntax is:

deploy stop [<module ID> [<module ID> ....]]

This command actually has a generalized JSR-88 syntax that specifies a TargetModuleID (instead of <module ID> in the syntax) that can include a target (cluster or host) identification. You specify this by using the following notation:

<target name>|<module ID/module name>

But this generalized syntax is not required by Geronimo at this time. Geronimo only supports a single target.

If you specify more than one <module ID>, Geronimo will attempt to stop each one.

The <module ID> you specify must represent a configuration that is current running on the Geronimo server.

The login Command

The main purpose of this command is save the tedious repeated use of --user <username> --password <password> options required when using the deployer repeatedly.

The general syntax for the command is:

deploy [--uri <uri to host>] --user <username>  --password <password> login

This command will save the login information (including both username and password) to the user’s home directory (may be at different locations, depending on the operating system used) in a file named .geronimo-deployer (which is hidden in a *nix environment).

The command recognizes the use of --uri or --host and --port. It will maintain and manage login information for multiple hosts that you deploy to.

The list-modules Command

This command displays all the deployed modules on the server. Running modules are represented by their module IDs in Geronimo. By default, the --all option is used, and all started or stopped modules are displayed. Any started modules are shown with a “+” sign next to them. All Web-tier modules that have a externally accessible URL associated with them will also have this URL shown next to the module.

The general syntax for the command is:

deploy list-modules [--all | --started | --stopped] [target*]

The --started command option will restrict the listing to only started modules. The --stopped command option will restrict the listing to only stopped modules.

The target option is applicable to generalized JSR-88 deployment. Geronimo typically only supports one single target at this point. In specialized situations involving multiple configuration stores (say, one that is read-only on CD-ROM, and one on disk), targets may be useful. This option is typically not used with Geronimo.

The list-targets Command

This command lists all the possible targets when issuing a command from the Geronimo server instance. Currently, Geronimo supports only one form of multiple targets - multiple configuration stores. This may be useful in specialized situations (say, one configuration store is read-only on CD-ROM, and the other one is on disk). However, the default, and typical Geronimo configuration involves only one single configuration store, and, therefore, one single target.

The general syntax for the command is:

deploy list-targets

This command may be more useful when using the deployer with other JSR-88–compliant servers. The following is the typical output from the command:

Available Targets:
  geronimo/j2ee-system/1.1/car?ServiceModule=geronimo/j2ee-system/1.1/car,j2eeTy
pe=ConfigurationStore,name=Local

The distribute Command

This command installs the module to the target but does not start it. The command does not mark the distributed module to start, and the module will not be started even if the server restarts. You must use the start command to start this module. The general command is as follows:

deploy distribute [--inPlace] [--targets target1;target2;target 3;...]  [module]
[plan]

The command options are meaningful when using a JSR-88–compliant server. Geronimo currently only supports a single target. The --inPlace option enables a server to execute the module without copying it to the configuration store (repository), but this is not supported by Geronimo at this time.

The search-plugins Command

This command will search for and display all available Geronimo plug-ins from a specified repository. You will also be prompted to select a plug-in for installation. The general command is as follows:

deploy search-plugins <repository URL>

For example, to see all of the plug-ins available at the www.geronimoplugins.com repository, use the following command:

deploy search-plugins  http://www.geronimoplugins.com/repository/geronimo-1.1/

A typical listing of available plug-ins may look like this:

    Security
        1 : Apache Directory 0.92 for Geronimo (1.1)

    Core Geronimo
            Geronimo Admin Console (Jetty) (1.1)
            Geronimo Admin Console (Tomcat) (1.1)
            Geronimo Welcome Web App (Jetty) (1.1)
            Geronimo Welcome Web App (Tomcat) (1.1)

    Scheduling
        2 : Quartz Job Deployer (0.1)
        3 : Quartz Scheduler Integration (0.1)
        4 : Quartz Scheduler Integration (0.2)
        5 : Quartz Job Deployer (0.2)

    Examples
            Jakarta JSP Examples (Jetty) (1.1)
        6 : Jakarta JSP Examples (Tomcat) (1.1)
            LDAP Example Web App (Jetty) (1.1)
        7 : LDAP Example Web App (Tomcat) (1.1)
        8 : LDAP Example Security Realm (1.1)
            Jakarta Servlet Examples (Jetty) (1.1)
        9 : Jakarta Servlet Examples (Tomcat) (1.1)

    Resources
            Oracle XA Driver for Console (Jetty) (1.0)
        10: Oracle XA Driver for Console (Tomcat) (1.0)

Install Service [enter number or 'q' to quit]:

You can then install a plug-in by simply entering the corresponding number.

The install-plugin Command

The install-plugin command can be used to install a specified plug-in (CAR) file. The general form of this command is as follows:

deploy install-plugin <CAR file of plugin>

For example, to install a previously downloaded Tomcat JSP examples CAR plug-in file, use the following command:

deploy install-plugin jsp-examples-tomcat-1.1.car

The result is:

Checking for status every 1000ms:
Downloading geronimo/jsp-examples-tomcat/1.1/car... (125%)
Downloading geronimo/jsp-examples-tomcat/1.1/car... (166%)
Downloaded geronimo/jsp-examples-tomcat/1.1/car (1088 kB) (100%)

    **** Installation Complete!
    Used existing: geronimo/j2ee-server//car
    Used existing: geronimo/tomcat//car

    Downloaded 1088 kB in 3s (362 kB/s)
    Now starting geronimo/jsp-examples-tomcat/1.1/car...

    Started geronimo/jsp-examples-tomcat/1.1/car @
    http://localhost:8080/jsp-examples


Deployment Using GUI Web Console

The Geronimo Web console provides a point-and-click interface for deploying modules and plans to a server instance. Under the hood, the console uses the same Geronimo JSR-88 deployment underpinnings to carry out its deployment duties.

To deploy a module or plan to a Geronimo instance using the GUI Web console, you must do the following:

  1. Log in to the Web console of the target Geronimo server.

  2. Click on the Deploy New link under the Applications heading.

  3. Specify either or both modules and the plan to be deployed.

  4. Optionally click the Start upon deploy checkbox; if it is not checked, the deployed module will initially be in the stopped state

Note that there is no need to specify a remote host when deploying through the Web console. This is because the Web console that you contact must be the Web console of the Geronimo server that you want to deploy to. Essentially, the actual deployment performed by the Web console is always on the local Geronimo server instance. In fact, your modules and plans are first uploaded to the server and then deployed locally by the Web console.

Figure B-1 shows the deployment user interface provided by the GUI Web console.

Image from book
Figure B-1: Using the Web console to deploy modules


Auto Deployment Using the Hot Deployer

Hot deploy functionality is included with Geronimo. Using the hot deployer, you can place modules into a hot deploy directory and they will be automatically deployed to the local server. The hot deployer checks the modification dates of the modules in the hot deploy directory regularly. If you make any changes to the files, the hot deployer will automatically redeploy the module on the local Geronimo server. If you delete hot-deployed modules from this directory, it will be undeployed on the server.

Be aware, however, that any modules you deleted from the hot deploy directory when the server is down will not be undeployed from the server.

By default, the hot deployer will examine the deploy directory for modules to hot deploy.


Index

A

activeio directory, 85
ActiveMQ
architecture, 391–393
Broker plan
ActiveMQ.cache GBean, 397
ActiveMQ.jdbc GBean, 397
ActiveMQ.journal GBean, 397
ActiveMQManager element
customizing, 397–401
dependencies element, 396
environment element, 396
geronimo.tcp.default, 397
geronimo.vm.localhost, 397
hidden-classes element, 396
moduleID element, 396
non-overridable-classes element, 396
SystemProperties, 397
Business tier, 60–61
clustering, 392
configuration, 156–157, 401–405
connectors, 392
controlling, 156–157
deploying
command-line deployer, 401–403
management console, 404–405
DR Clustering, 392
DR (disaster recovery), 392
EIS tier, 62–63
Geronimo console and, 405–406
Network Services, 392
Queue Region, 391
resource adapter
configuration, 407–421
contents, 412–413
deployment plan, 408–409
JMS resources, 406–407
STOMP (Streamlining Text Oriented Messaging Protocol), 392
Topic Region, 391
activemq directory, 85
<adminobject> element, 428 , 429
adminobject item Resource Adapter plan, 286
adminobject-class item Resource Adapter plan, 286
adminobject-instance item Resource Adapter plan, 286
adminobject-interface item Resource Adapter plan, 286
Agent level, JMX, 120
antlr directory, 85
Apache Group, Apache Software Foundation and, 41
Apache Server, history of, 40
ASF (Apache Software Foundation)
introduction, 40
Web site, 1
AppController, 248
application
clients, support for, 68–69
deploying, Web console and, 164–166
Application clients, deploying, 430–432
Application EARs portlet, 22
application modules, starting, 27
applications
client application container, 274
deployment
deployer tool, 16–20
EAR file, 16
undeploying, 27
Web console, 20–23
enterprise
deployed, 166–168
EJB deployment and, 60
listing running, 21
security in
EJB security, 376–378
security declaration, 378–388
security descriptor, 378–388
Web security, 374–375
undeploying, 27
ASF (Apache Software Foundation)
introduction, 40
Web site, 1
asm directory, 85
assemblies
binding, 79
creating, 79
introduction, 78
modules comparison, 79
repositories and, 79
<assembly-description> subelements, 254
attributes, configuration, Web console, 36–37
authentication
description, 339
introduction, 337
AuthorConnectionsPool, 269
AuthorEntityCMPBean, 248
authorization
description, 339–340
introduction, 337
JACC and, 344–345
security policies and, 339
AuthorsBean, 248
authors.jsp, 247
AuthorsLister Java class, 311
AuthorsLocator Java class, 311 , 321
AuthorWS Java class, 311 , 321
auto deployment, Hot Deployer, 445
axis directory, 85
AXIS, Web services, 64


Previous Page
Next Page

Index

B

bin directory
client.jar, 81
deployer.jar, 81
server.jar, 81
shutdown.jar, 81
upgrade.jar, 81
binary distributions
introduction, 5
Jetty, 5–6
Tomcat, 5–6
bindings, IDL, 325
blocking-timeout-milliseconds item Resource Adapter plan, 286
builds
introduction, 3
latest milestone build, 4
latest unstable build, 4
Business tier
ActiveMQ, 60–61
components deployable, 58–59
deployable module, 59
EJBs, deploying, 60
OpenEJB, 60
Business tier EJBs, deploying, openejb-jar.xml, 426–427


Previous Page
Next Page

Index

C

<callback-handler> element, 432
CAR (configuration archive), modules, 87–89
CertificateChainLoginModule, 360
CertificatePropertiesFileLogin Module, 360
cglib directory, 85
classes, Java
AuthorsLister, 311
AuthorsLocator, 311, 321
AuthorsWS, 321
AuthorWS, 311
GetAuthors, 311, 321
GetAuthorsResponse, 311, 321
client application container, 274
client.jar, 81
CMP entity bean, Derby databases, 260–262
command-line deployer
ActiveMQ deployment, 401–405
commands
deploy, 439
distribute, 442–443
help, 439
install-plugin, 444
list-modules, 442
list-targets, 442
login, 441–442
redeploy, 440
search-plugins, 443
start, 441
stop, 441
undeploy, 440
JSR-88 and, 101–102
options
-driver, 438
-host, 437
-offline, 438
-password, 438
-port, 437
-syserr, 438
-uri, 437
-user, 438
-verbose, 438
common-beanutils directory, 85
common-cli directory, 85
common-digester directory, 85
commons-collections directory, 85
commons-discovery directory, 85
commons-el directory, 85
commons-logging directory, 85
commons-modeler directory, 85
concurrent directory, 85
config-property-setting item Resource Adapter plan, 286
config.ser file, 88
configuration
assembly-time, 35
attributes modification, Web console, 36–37
PostgreSQL, clustered, 299–300
run-time, 35
transactions, 262–265
configuration archive (CAR), modules, 87–89
config.xml file
connectors, Web containers, 189–190
GBean components, 31–34
installation and, 8–10
JavaMail system module and, 266–267
module configuration, 30–31
<modules> subelements, 30
ORB parameters, 335
connection-definition item Resource Adapter plan, 285
connectiondefinition-instance item Resource Adapter plan, 285
connectionfactory-interface item Resource Adapter plan, 285
connectionmanager item Resource Adapter plan, 285
connector item Resource Adapter plan, 284
ConnectorGBean, 218
container services
configuration management, 53, 72
manageability, 53, 72
naming and directory, 53, 70–71
security, 53, 71
transaction, 53, 71
<container-config> element, 425
container-managed transactions
description, 262
JavaMail, 267
container-managed-security item Resource Adapter plan, 285
<context-root> element, 425
ControllerServlet, 16
CORBA
clients, support, 332–334
GIOP (General Inter-ORB Protocol), 327
IDL (Interface Definition Language), 325–326
IIOP (Internet InterORB Protocol), 327
interoperability, 67–68
Java-based, 327–328
ORB (Object Request Broker), 326–327, 335
parent module dependency, 334
security, 329
Web services comparison, 324–325
CSIv2
GBeans, 329
security
client-side, 331–332
Geronimo support, 329
server-side, 330
CSS GBeans
NoSecurity, 332
NoSecurityIdentityTokenCert, 332
NoSecurityIdentityToken Principal, 332
SSLClientCert, 332
SSLClientPassword, 332
SSLIdentityTokenCert, 332
SSLIdentityTokenPrincipal, 332


Previous Page
Next Page

Index

D

Database Manager portlet, 173
database pools, Web console, 291–293
databases
connections pool, 268–274
embedded, database information, 172–173
pools, installing, 162–163
<db-syntax-factory> element, 427
debug console
architecture, 118
filtering output, 133–135
installation, 128
jconsole, JMX console, 129–131
url for access, 132–133
declarative security, 339
<default-principal> element, 378–379
dependencies item Resource Adapter plan, 284
deploy command, 11 , 100–101 , 439
deploy directory, 81
deploy.bat, 17
deployer
binary, 100
commands
deploy, 106
distribute, 107
help, 108
install-plugin, 109
list-modules, 108
list-targets, 108
login, 107
redeploy, 107
search-plugins, 109
start, 106
stop, 107
undeploy, 107
--driver option, 105
--host option, 105
JDBC resources, 290–291
offline installation, 103–104
--offline option, 106
--password option, 105
--port option, 105
run-time state information, 110–111
--syserr option, 105
--uri option, 105
--user option, 105
--verbose option, 106
deployer command, syntax, 104
deployer tool
application deployment, 17–20
deployment information, 18
installation verification, 11
deployer.jar, 81
deploy.jar file, deploy command, 104
deployment
applications
deployer tool, 17–20
EAR file, 16
Web console, 20–23
Web console and, 164–166
architecture
assignment of module IDs, 181–182
deployed module in repository, 180–181
auto deployment, Hot Deployer, 445
Business tier EJBs, openejb-jar.xml, 426–427
containers, 259–260
deployable modules, 176
descriptors
Geronimo-specific, 25–26
J2EE descriptors, 175–178
standard, 24–25
EAR file, 16
external deployment plan, 26
GUI Web console, 444–445
Hot Deployer, 444–445
JDBC plan for PostgreSQL, 288–289
JDBC, resources, 289–297
Maven plug-in, 111–115
modules, to server instance, 100–101
plans
internal to module, 179–180
naming, 178–179
stateless session EJB as Web service, 320–324
troubleshooting
console output, 136–137
deployment plan correction, 139–140
log file, 137–139
querying components from deployed application, 140–142
viewing attributes of managed object, 142–144
web applications, Geronimo-specific plan, 190–191
Web service WAR on Geronimo, 311–320
Web services, 318–319
deployment descriptors
Geronimo-specific, 25–26
introduction, 24–26
J2EE specification schemas, 432–433
standard, 24–25
Web containers, namespaces, 193–199
web services, webservices.xml, 312–315
deploy.sh, 17
Derby
CMP entity bean, 260–262
EIS tier, 63
<description> element, 379
DirectConfigurationEntry GBean, 347–348
directories
installation directory
bin directory, 80–81
deploy directory, 80, 81
docs directory, 80, 81
lib directory, 80, 81–83
repository directory, 80, 83–90
schema directory, 80, 90–93
var directory, 80, 93–97
repository, top-level directories, 85
<distinguished-name> element, 379
distribute command, deployer, 107 , 442
Distributed Services level, JMX, 121
distributions
binary, 5
source code, 5
docs directory, 81
download page, 3
-driver option, command-line deployer, 438
--driver option, deployer, 105


Previous Page
Next Page

Index

E

EAR (Enterprise Application Archive) files
deployment descriptors, 24–26
introduction, 16
modules, local references, resolving, 245–246
EIS tier
ActiveMQ, 62–63
Derby, 63
geronimo-ra.xml, 427–429
introduction, 61
JavaMail, 63
EJB JAR files
deployment descriptors, 25
describing, 251–252
external references, 244–245
<ejb-class> element, 252
ejb-jar.xml, deployment descriptor, 248–251
<ejb-name> element, 252
<ejb-ql-compiler-factory> element, 427
EJBs
access
external, 242
internal, 242
configuration, 259
deploying, enterprise application and, 60
EJB JAR, describing, 251–252
EJB-based Web service implementation, 321–322
<ejb-local-ref>, 259
<ejb-ref>, 259
external classes, 259
OpenEJB2 and, 242
references
mapping external, 258
mapping internal, 258
resolving in Geronimo, 257
session beans, 58
elements
<abstract-schema-name>, 253
<activation-config>, 254
<adminobject>, 428
<callback-handler>, 432
<cmp-field>, 253
<cmp-version>, 253
common to session and entity, 252
<container-config>, 425
<context-root>, 425
<db-syntax-factory>, 427
<default-principal>, 378–379
<description>, 379
<distinguished-name>, 379
<ejb-class>, 253
<ejb-name>, 253
<ejb-ql-compiler-factory>, 427
<enforce-foreign-key-constraints>, 427
<enterprise-beans>, 427
<ext-module>, 430
<login-domain-principal>, 380
<login-module>, 365–367
<login-module-ref>, 364–365
<message-destination-link>, 254
<message-destination-type>, 254
<messaging-type>, 254
<module>, 430
<named-username-password-credential>, 380
<naming:cmp-connection-factory>, 427
<naming:ejb-ref>, 432
<naming:gbean-ref>, 431
<naming:message-destination>, 425, 427, 432
<naming:resource-env-ref>, 432
<naming:resourceref>, 432
<naming:service-ref>, 432
<naming:web-container>, 425
<persistence-type>, 253
<prim-key-class>, 253
<primkey-field>, 253
<principal>, 381
<realm-name>, 432
<realm-principal>, 381
<reentrant>, 253
<relationships>, 427
<resource>, 432
<resourceadapter>, 428
<role>, 382
<role-mapping>, 382
<security>, 383
<security-identity>, 252, 253, 254
<security-realm-name>, 425
<security-role-ref>, 252, 253
<security:security>, 425, 427, 430
<session-type>, 252
<sys:client-environment>, 431
<sys:environment>, 425, 426, 428, 430
<sys:gbean>, 425, 427, 428, 430, 432
<sys:server-environment>, 431
<transaction-type>, 252, 254
email
JavaMail, 265–266
MailSession GBean, 266
embedded databases
Database Manager portlet, 173
information, obtaining, 172–173
<enforce-foreign-key-constraints> element, 427
EngineGbean, 223
Enterprise Application Archive files. See EAR files
enterprise applications
client applications, 168
deploying, 429–430
EJB deployment and, 60
EJB JARs, 168
J2EE Connectors, 168
system modules, 168
Web applications, 168
<enterprise-beans> element
<entity> subelement, 251
<message-driven> subelement, 251
<session> subelement, 251
entity beans
CMP
deploying, 248–254
Derby databases, 260–262
elements
<abstract-schema-name>, 253
<cmp-field>, 253
<cmp-version>, 253
common in session beans, 251–252
<persistence-type>, 253
<prim-key-class>, 253
<primkey-field>, 253
<reentrant>, 253
<security-identity>, 253
<security-role-ref>, 253
entity EJBs
deploying, example, 247–265
introduction, 59, 241
environment item Resource Adapter plan, 284
external references
EJB JAR files, 244–245
mapping, 246–247
<ext-module> element, 430


Previous Page
Next Page

Index

F

failed state, modules, 29
FileAuditLoginModule, 360
foo( ) method, 309


Previous Page
Next Page

Index

G

GBean components, config.xml file, 31–34
gbean item Resource Adapter plan, 286
GBeans
ActiveMQ, 397
ActiveMQ.cache, 397
ActiveMQ.jdbc, 397
ActiveMQ.journal, 397
AJP13Connector, 204–205
configuration management, 77
ConnectorGBean, 218
description, 76
DirectConfigurationEntry, 342, 347–348
EngineGbean, 223
GenericSecurityRealm, 350
GeronimoLoginConfiguration, 342
GeronimoSecurityRealm, 342
HostGBean, 225
HTTPConnector, 200–201
HTTPSConnector, 202–203
HttpsConnectorBean, 220
IdentityTokenNoSecurity, 330
JaasLoginModuleUse, 354–355
JettyContainerImpl, 200
lifecycle management, 78
LoginModuleGBean, 352–353
MailSession, 266
manageability, 78
ManagerGBean, 227
methods, 76
modules and, 77–78
NCSARequestLog logger bean, 205
NoSecurity, 332
NoSecurityIdentityTokenCert, 332
NoSecurityIdentityToken Principal, 332
properties, 76
RealmGBean, 227
SecurityService, 386–388
ServerRealmConfigurationEntry, 348–349
SSLClientCert, 330, 332
SSLClientCertIdentityToken, 330
SSLClientPassword, 330, 332
SSLIdentityToken, 330
SSLIdentityTokenCert, 332
SSLIdentityTokenPrincipal, 332
Tomcat
ConnectorGBean, 218
EngineGbean, 223
HostGBean, 225
HttpsConnectorBean, 220
ManagerGBean, 227
RealmGBean, 227
TomcatContainer, 218
ValveGBean, 228
TomcatContainer, 218
ValveGBean, 228
General Inter-ORB Protocol (GIOP), 327
GenericSecurityRealm, 341
GenericSecurityRealm GBean, 350–352
Geronimo
Apache spirit and, 42
project timeline, 43–47
security architecture, 337
as top-level ASF project, 42–48
geronimo directory, 85
Geronimo server, installation, running, 10–11
geronimo-application-client.xml
namespaces, 431
top-level elements
<callback-handler>, 432
<naming:ejb-ref>, 432
<naming:gbean-ref>, 431
<naming:message-destination>, 432
<naming:resource-env-ref>, 432
<naming:resourceref>, 432
<naming:service-ref>, 432
<realm-name>, 432
<resource>, 432
<sys:client-environment>, 431
<sys:gbean>, 432
<sys:server-environment>, 431
geronimo-application.xml
description, 424
namespaces, 429
top-level elements
<ext-module>, 430
<module>, 430
<security:security>, 430
<sys:environment>, 430
<sys:gbean>, 430
geronimo-client.xml, 424
GeronimoLoginConfiguration, 346
GeronimoPasswordCredentialLogin Module, 360
geronimo-properties-realm security service, 209
geronimo-ra.xml
description, 424
namespaces, 428
top-level elements
<adminobject>, 428
<resourceadapter>, 428
<sys:environment>, 428
<sys:gbean>, 428
geronimo-spec directory, 85
Geronimo-specific deployment descriptors, 25–26
geronimo-web.xml
description, 423
introduction, 190–191
top-level elements
<container-config>, 425
<context-root>, 425
JNDI Environment References, 425
<naming:message-destination>, 425
<naming:web-container>, 425
<security-realm-name>, 425
<security:security>, 425
<sys:environment>, 425
<sys:gbean>, 425
getAuthors( ) method, invoking, Web service client and, 319
GetAuthors Java class, 311 , 321
GetAuthorsResponse Java class, 311 , 321
GIOP (General Inter-ORB Protocol), 327


Previous Page
Next Page

Index

H

hardware, platform requirements, 6–7
help command, deployer, 108 , 439
hidden-classes item Resource Adapter plan, 284
<home> element, 252
--host option, deployer, 105 , 437
HostGBean, 225
Hot Deployer, 445
howl directory, 85
HTTP, Web services and, 306–307
HttpsConnectorBean, 220


Previous Page
Next Page

Index

I

IdentityTokenNoSecurity TSS GBean, 330
IDL (Interface Definition Language), CORBA, 325–326
idle-timeout-minutes item Resource Adapter plan, 286
IIOP (Internet InterORB Protocol), 327
implemented-interface item Resource Adapter plan, 285
Install New Applications portlet, 22
installation
config.xml file, 8–10
debug console, 128
Geronimo server, running, 10–11
hardware requirements, 6–7
JVM and, 7–8
offline, deployer, 103–104
plug-ins, 109–110
verification, 11–12
installation directory
bin directory
client.jar, 81
deployer.jar, 81
introduction, 80
server.jar, 81
shutdown.jar, 81
upgrade.jar, 81
deploy directory, 81
docs directory, 81
lib directory
endorsed subdirectory, 83
ext subdirectory, 83
introduction, 81–82
repository directory
artifacts, 83–84
coordinates, 83–84
top-level directories, 85
schema directory, 90–93
var directory
activemq directory, 93
catalina directory, 93, 94
config directory, 93, 94
derby directory, 93, 97
installed modules, preventing startup, 95
installed modules, startup order, 95
log directory, 93, 97
module configuration, overriding GBean attributes, 96
security directory, 93, 97
shared directory, 94
tmp directory, 94
txlog directory, 94
install-plugin command, deployer, 109, 444
Instrumentation level, JMX, 119
Interface Definition Language (IDL), CORBA, 325–326
interface proxy/tie component (JAX-RPC), 309
Internet InterORB Protocol (IIOP), 327
interoperability
CORBA, 67–68
J2EE EIS tier and, 67
IP addresses, service listeners, 34–35


Previous Page
Next Page

Index

J

JAAS (Java Authentication and Authorization Service)
DirectConfigurationEntry GBean, 342
GeronimoLoginConfiguration GBean, 342
GeronimoSecurityRealm GBean, 342
introduction, 337
login coordinator, 343
login modules
chaining, 342
configuration, 346–352
introduction, 341
JaasLoginModuleUse, 342
J2SE, configuration, 345–346
LoginModule, 341
ServerRealmConfigurationEntry, 342
web site, 338
JaasLoginModuleUse GBean, 354–355
JACC (Java Authorization Contract for Containers)
authorization and, 344–345
introduction, 337
web site, 338
JAR files, deployment descriptors, 25–26
Java, classes
AuthorsLister, 311
AuthorsLocator, 311, 321
AuthorWS, 311, 321
GetAuthors, 311, 321
GetAuthorsResponse, 311, 321
JavaMail
config.xml and, 266–267
container-managed session
linking to, 267–268
referencing, 267
EIS tier, 63
IMAP and, 265
POP and, 265
SMTP and, 265
transports, 265–266
Java Management Extensions. See JMX
Java Message Service. See JMS
Java Virtual Machine. See JVM
JAX-RPC
interface proxy/tie component, 309
mapping files, 321
Web services, 307–309
web.xml deployment descriptor, 315–316
JCA (J2EE Connector Architecture), RAR file, 280–281
jconsole
connecting Geronimo, 130–131
starting, 130
JDBC
deployment plan, PostgreSQL, 288–289
drivers, downloading, 293–294
resources
configuration, 281–289
deploying, 289–297
jdom directory, 85
J2EE (Java 2 Enterprise Edition)
Application clients, deploying, 430–432
deployment descriptors, XML schema, 177
J2EE compliant release of Geronimo, 4
parent keys, mandatory, 125
schemas, deployment descriptors, 432–433
software components
building phase, 26
configuration phase, 26
deployment descriptors, 24–26
distribution phase, 27
introduction, 23
loading, 26
starting, 26
stopping, 26
tiers
Business, 54, 58–61
Client support, 54
EIS, 54, 61–63
Interoperability, 54
Web, 54, 55–58
Web services, 54, 63–66
Jetty
GBeans
AJP13Connector, 204–205
HTTPConnector, 200–201
HTTPSConnector, 202–203
JettyContainerImpl, 200
NCSARequestLog logger GBean, 205
introduction, 5–6
Little-G and, 6
Web tier, 58
JMS (Java Message Service)
MDBs and, 59
resource groups
Geronimo console and, 415–421
introduction, 163–164
options, 416
resources
ActiveMQ, 406–407
connection factories, 406, 418
deploying, 413–415
destinations, 407
sessions, 407
JMX (Java Management Extensions)
Agent level, 120–121
debug console and, 118
Distributed Services level, 120–121
Instrumentation level, 119
introduction, 118
login, remote service, 343–344
JSP, Web tier and, 56–57
JSR-77
domains, 127
manageable states, 127–128
MEJB, 121–123
object names, 123–127
JSR-88
benefits of, 102–103
command-line deployer and, 101–102
juddi directory, 85
junit directory, 85
JVM (Java Virtual Machine)
installation and, 7–8
remote management, 130


Previous Page
Next Page

Index

L

LDAPLoginModule, 357
lib directory
endorsed subdirectory, 81–83
ext subdirectory, 81–83
overview, 81–83
licenses
Apache License 2.0, 50–51
BSD, 49
GNU’s General Public License (GPL), 50
LGPL, 50
MIT, 49
New BSD, 49
list-modules command, deployer, 12 , 108 , 442
list-targets command, deployer, 108 , 442
Little-G server
Jetty and, 6
Tomcat and, 6
<local> element, 252
local references, EAR modules, 245–246
<local-home> element, 252
local-transaction item Resource Adapter plan, 285
lock down, 388–389
login command, deployer, 107 , 441
login domains, description, 340–341
login modules, JAAS, configuration, 346–352
<login-domain-principal> element, 380
<login-module> element, 365–367
LoginModuleGBean, 352–353
<login-module-ref> element, 364–365
LoginModules
CertificateChainLoginModule, 360
CertificatePropertiesFileLogin Module, 360
FileAuditLoginModule, 360
GeronimoPasswordCredentialLogin Module, 360
LDAPLoginModule, 357
LoginModuleGBean and, 352
PropertiesFileLoginModule, 356
RepeatedFailureLockoutLogin Module, 362
SQLLoginModule, 356
xml-reference login-config and, 363–367
log4j directory, 85


Previous Page
Next Page

Index

M

MailSession GBean, 266
ManagerGBean, 227
Mandatory EJB attribute, 264
mapping external references, 246–247 , 258
mapping files
JAX-RPC, 321
WSDL, 321
mapping internal references, EJBs, 258
match-all item Resource Adapter plan, 285
match-one item Resource Adapter plan, 285
Maven deployment plug-in, 111–115
max-size item Resource Adapter plan, 286
MDBs (message driven beans)
elements
<activation-config>, 254
<ejb-class>, 253
<ejb-name>, 253
<message-destination-link>, 254
<message-destination-type>, 254
<messaging-type>, 254
<security-identity>, 254
<transaction-type>, 254
introduction, 59
MEJB (Management EJB), 121–123
MEP (Message Exchange Pattern), 307
message-destination-name item Resource Adapter plan, 286
META-INF directory, configuration files, 87
min-size item Resource Adapter plan, 286
<module> element, 430
moduleId item Resource Adapter plan, 284
modules
assemblies and, 78–79
CAR, 87–89
configuration, config.xml, 30–31
deployed
introduction, 29
managing, 166–168
storing associated with configuration, 89–90
deploying, to server instance, 100–101
deployment plan, 77
description, 29
GBeans and, 77–78
lifecycle, states, 29
mx4j directory, 86


Previous Page
Next Page

Index

N

<named-username-password-credential> element, 380
namespaces in descriptors, Web containers and, 193–199
<naming:cmp-connection-factory> element, 427
<naming:ejb-ref> element, 432
<naming:gbean-ref> element, 431
<naming:message-destination> element, 425 , 427 , 432
<naming:resource-env-ref> element, 432
<naming:resourceref> element, 432
<naming:service-ref> element, 432
<naming:web-container> element, 425
Never EJB attribute, 264
non-overridable-classes item Resource Adapter plan, 284
no-pool item Resource Adapter plan, 285
NoSecurity CSS GBean, 332
NoSecurityIdentityTokenCert CSS GBean, 332
NoSecurityIdentityTokenPrincipal CSS GBean, 332
no-transaction item Resource Adapter plan, 285
NotSupported EJB attribute, 264


Previous Page
Next Page

Index

O

Object Request Broker (ORB), CORBA, 326–327 , 335
offline installation, deployer, 103–104
-offline option, command-line deployer, 438
--offline option, deployer, 106
OMG (Object Management Group), 306
open source software
benefits, 47–48
licenses
Apache License 2.0, 50–51
BSD license, 49
GNU General Public License (GPL), 50
LGPL, 50
MIT license, 49
New BSD license, 49
overview, 48
OpenEJB, Business tier and, 60
openejb directory, 86
openejb-jar.xml
cmp-connection-factory subelement, 256
db-syntax-factory subelement, 256
dependency subelement, 256
description, 424
ejb-ql-connection-factory subelement, 256
enforce-foreign-key-constraints subelement, 256
enterprise-beans subelement, 256
gbean subelement, 256
hidden-classes subelement, 256
import subelement, 256
message-destination subelement, 256
non-overridable-classes subelement, 256
relationships subelement, 256
security subelement, 256
top-level elements
<db-syntax-factory>, 427
<ejb-ql-compiler-factory>, 427
<enforce-foreign-key-constraints>, 427
<enterprise-beans>, 427
<naming:cmp-connection-factory>, 427
<naming:message-destination>, 427
<relationships>, 427
<security:security>, 427
<sys:environment>, 426
<sys:gbean>, 427
ORB (Object Request Broker), CORBA, 326–327 , 335
org/apache/derby directory, 86
org/apache/geronimo/specs directory, 86
org/apache/Pluto directory, 86
outbound-resource-adapter item Resource Adapter plan, 284


Previous Page
Next Page

Index

P

partition-by-connectionrequestinfo item Resource Adapter plan, 286
partition-by-subject item Resource Adapter plan, 286
partitioned-pool item Resource Adapter plan, 285
-password option, command-line deployer, 438
--password option, deployer, 105
pg_ctl utility, 279
plug-ins
commands for, 108–109
downloading, 168
installing, 109–110
searching, 109–110
-port option, command-line deployer, 437
--port option, deployer, 105
portlet-api directory, 86
portlets
Application EARs, 22
Database Manager, 173
description, 21
Install New Applications, 22
Web console, 148
ports, service listeners, 34–35
POSTGRES project, 277
postgres user, 279
PostgreSQL
architecture, 278–279
clustered
configuration, 299–300
deployed, 303
introduction, 277
Sequoia and, 297–303
starting, 279–280
postgresql-plan.xml, output, 290
<principal> element, 381
progeron.ear file
archive file bundling, 18
deployment, 17
introduction, 16
progeron-ejbs.jar, 19
progeron.war, 19
programmatic security, 339
project home page, 2
PropertiesFileLoginModule, 356
protected resources, 339


Previous Page
Next Page

Index

R

RAR files
deployment descriptors, 25–26
JCA, 280–281
RealmGBean, 227
<realm-name> element, 432
<realm-principal> element, 381
realms, Tomcat, 232–235
redeploy command, deployer, 107 , 440
<relationships> element, 427
releases
1.0, 4
1.1, 4
introduction, 3
M3, 5
M4 (Milestone 4), 5
M5 (Milestone 5), 5
<remote> element, 252
RepeatedFailureLockoutLogin Module, 362
repository
artifacts, installing, 159–161
assemblies and, 79
as configuration store, 86–87
description, 75
directories, top-level, 85
repository directory
activeio subdirectory, 85
activemq subdirectory, 85
antlr subdirectory, 85
artifacts, 83–84
asm subdirectory, 85
axis subdirectory, 85
cglib subdirectory, 85
common-beanutils subdirectory, 85
common-cli subdirectory, 85
common-digester subdirectory, 85
commons-collections subdirectory, 85
commons-el subdirectory, 85
commons-logging subdirectory, 85
commons-modeler subdirectory, 85
concurrent subdirectory, 85
coordinates, 83–84
geronimo subdirectory, 85
geronimo-spec subdirectory, 85
howl subdirectory, 85
jdom subdirectory, 85
juddi subdirectory, 85
junit subdirectory, 85
log4j subdirectory, 85
mx4j subdirectory, 86
openejb subdirectory, 86
org/apache/derby subdirectory, 86
org/apache/geronimo/specs subdirectory, 86
org/apache/Pluto subdirectory, 86
portlet-api subdirectory, 86
scout subdirectory, 86
stax subdirectory, 86
tomcat subdirectory, 86
wsdl4j subdirectory, 86
xerces subdirectory, 86
xmlbeans subdirectory, 86
xpp3 subdirectory, 86
xstream subdirectory, 86
Request Response Message Exchange Pattern (MEP), 307–308
Required EJB attribute, 264
RequiresNew EJB attribute, 264
resource adapter plan contents, 286
resource adapter, TranQL, 287
<resource> element, 432
<resourceadapter> element, 428
resourceadapter item Resource Adapter plan, 284
resourceadapter-instance item Resource Adapter plan, 284
resourceadapter-name item Resource Adapter plan, 284
resources, deploying JDBC, 289–297
<role> element, 382
<role-mapping> element, 382
running state, modules, 29
run-time state information, deployer, 110–111


Previous Page
Next Page

Index

S

schema directory, 90–93
scout directory, 86
scripts, startup.sh, 10
searches, plug-ins, 109–110
search-plugins command, deployer, 109, 443
security
architecture
authentication, 339
authorization, 339–340
login domains, 340–341
security realms, 340–341
configuration
console realm, 170
keystore, 171–172
security realm, 170–171
declaration, 378–388
declarative, 339
descriptor
<default-principal> element, 378–379
<description> element, 379
<distinguished-name> element, 379
<login-domain-principal> element, 380
<named-username-password-credential> element, 380
<principal> element, 381
<realm-principal> element, 381
<role> element, 382
<role-mapping> element, 382
<security> element, 382
policies, 339
principals, 339
programmatic, 339
protected resources, 339
subsystem importance, 338
<security> element, 383
security realms, 340
configuration, 367–372
description, 340
GenericSecurityRealm GBean, 350
xml-references, 363–364
<security-realm-name> element, 425
<security:security> element, 425 , 427 , 430
SecurityService GBean, overriding, 386–388
SEI (Service Endpoint Interface), 309
select-one-assume-match item Resource Adapter plan, 285
Sequoia
configuration, 300–303
PostgreSQL and, 297–303
server.jar, 81
ServerRealmConfigurationEntry GBean, 348–349
service endpoints, mapping session beans to, 322
service listeners
IP address, 34–35
port address, 34–35
<service-endpoint> element, 252
<service-ref> element
<jaxrpc-mapping> subelement, 316
<service-interface> subelement, 316
<service-ref-name> subelement, 316
<wsdl-file> subelement, 316
services, ports, 11
servlets, Web tier and, 56–57
session beans
deploying, 248–254
elements
common in entity beans, 251–252
<security-identity>, 252
<security-role-ref>, 252
<session-type>, 252
<transaction-type>, 252
introduction, 58
mapping to service endpoints, 322
overview, 241
stateless, as Web services, 320–324
session EJBs
as CORBA components
CORBA 2.3 security, 329
CORBA client support, 332–334
ORB parameters, config.xml and, 335
parent modules, 334
security configuration, 330–332
deploying, example, 247–265
shutdown.jar, 8 1
single-pool item Resource Adapter plan, 285
SOAP, Web services, 307–308
software components
building phase, 26
configuration phase, 26
deployment descriptors, standard, 24–25
distribution phase, 27
EJB, 24
JCA connectors, 24
JSP,24
lifecycle, 28
loading, 26
MDB, 24
modules
failed state, 29
overview, 26
running state, 29
starting state, 29
servlets, 24
starting, 26
stopping, 26
source code distributions, 5
Spring Framework, 77
SQLLoginModule, 356
SSLClientCert CSS GBean, 332
SSLClientCert TSS GBean, 330
SSLClientCertIdentityToken TSS GBean, 330
SSLClientPassword CSS GBean, 332
SSLClientPassword TSS GBean, 330
SSLIdentityToken TSS GBean, 330
SSLIdentityTokenCert CSS GBean, 332
SSLIdentityTokenPrincipal CSS GBean, 332
start command, deployer, 106 , 441
starting state, modules, 29
startup command, 10
startup.sh script, 10
stateless session EJBs as Web services, 320–324
stax directory, 86
STOMP (Streamlining Text Oriented Messaging Protocol), 392
stop command, deployer, 107 , 441
stubs, 309
Subversion, 3
Supports EJB attribute, 264
<sys:client-environment> element, 431
<sys:environment> element, 425 , 428 , 430
-syserr option, command-line deployer, 438
--syserr option, deployer, 105
<sys:gbean> element, 425 , 427 , 428 , 430 , 432
<sys:server-environment> element, 431


Previous Page
Next Page

Index

T

Target Security Service (TSS), 329
thread-caching item Resource Adapter plan, 285
tiers
Business
ActiveMQ, 60–61
EJBs, deploying, 60
OpenEJB, 60
Business tier
components deployable, 58–59
deployable module, 59
overview, 54
client support, 54
EIS
ActiveMQ, 62–63
Derby, 63
introduction, 54
JavaMail, 63
interoperability, 54
Web
components deployable, 56–57
containers, 56
Jetty, 58
JSP, 56–57
lightweight server solutions, 56
overview, 54–57
presentation layer components, 55
servlets, 56–57
Tomcat, 57–58
Web services
AXIS, 64
integration, 64–66
introduction, 54
overview, 63–64
UDDI support, 66
Tomcat
architecture, 210–211
configuration
architecture and, 210–211
connectors, 229
context level, 235–238
files, Geronimo equivalents, 211
introduction, 209
SSL connector, 230
virtual hosts, 230
connectors, configuration, 229
context level configuration, 235–238
GBeans
ConnectorGBean, 218
EngineGbean, 223
HostGBean, 225
HttpsConnectorBean, 220
ManagerGBean, 227
RealmGBean, 227
TomcatContainer, 218
ValveGBean, 228
geronimo-web.xml, 235–238
introduction, 5–6
Little-G and, 6
plan.xml, 212–216
realms, 232–235
running, 208–209
server.xml, 212
valves, 231–232
verification, 208–209
Web tier, 57–58
tomcat directory, 86
TomcatContainer
Connector objects, 210
introduction, 218
Realm objects, 211
Valve objects, 211
TomcatWebConnector GBean component, 34
tranql directory, 86
transaction-caching item Resource Adapter plan, 285
transaction-log item Resource Adapter plan, 285
transactions
attributes
Mandatory, 264
Never, 264
NotSupported, 264
Required, 264
RequiresNew, 264
Supports, 264
boundaries, 263
configuration, 262–265
TSS GBeans
IdentityTokenNoSecurity, 330
SSLClientCert, 330
SSLClientCertIdentityToken, 330
SSLClientPassword, 330
SSLIdentityToken, 330
TSS (Target Security Service), 329


Previous Page
Next Page

Index

U

UDDI (Universal Description Discovery and Integration) server
jUDDI, 66
Tomcat, 21
undeploy command, deployer, 107 , 440
Uninstall command, 22
upgrade.jar, 81
-uri option, command-line deployer, 437
--uri option, deployer, 105
-user option, command-line deployer, 438
--user option, deployer, 105


Previous Page
Next Page

Index

V

ValveGBean, 228
valves, Tomcat, 231–232
var directory
activemq directory, 93
catalina directory, 93
config directory, 93
derby directory, 93
log directory, 93
security directory, 94
shared directory, 94
tmp directory, 94
txlog directory, 94
-verbose option, command-line deployer, 438
--verbose option, deployer, 106
verification, installation, 11–12


Previous Page
Next Page

Index

W

WAR (Web application archive) files
deployment descriptors, 24–26
Web services
cross-server compatible, 316–317
deploying on Geronimo, 311–320
Web tier container, 57
Web applications
deployment
Geronimo-specific plan, 190–191
overview, 191–193
starting, 191–193
stopping, 191–193
undeploying, 191–193
Web console
adding users, 149–150
application deployment and, 20–23, 164–166
applications, exposing via Web server, 158–159
architecture, 148
attributes, configuration, 36–37
connectors, Web containers, 187–189
databases, pools, installing, 162–163
GUI, deployment and, 444–445
JDBC resource deployment, 291–296
JMS resource groups, 163–164
JVM, viewing properties, 151
log files
searching, 151–153
viewing, 151–153
logging on, 148–149
login page, 20
modules, deployed, managing, 166–168
properties files, 150
repository, artifacts, installing, 159–161
server connectors, configuration, 154–156
server shutdown, 153
system information, 150
thread pools, monitoring, 157
Web containers
applications, configuration, 190–199
classes, hiding, 197–199
configuration, default, 185–187
connectors
config.xml, 189–190
Web console and, 187–189
descriptors, namespaces, 193–199
Jetty
config.xml, 185
Tomcat common elements, 196
Jetty and Tomcat at same time, 184–190
Tomcat
config.xml, 184–185
Jetty common elements, 196
Web Service Description Language (WSDL), 307 , 321
Web services
AXIS, 64
context root, 317
CORBA comparison, 324–325
deploying, 318–319
deployment context, 323
deployment descriptor, webservices.xml, 312–315
EJB-based implementation, 321–322
Geronimo and, 310–311
HTTP and, 306–307
integration, 64–66
interfaces, 308
JAX-RPC, 307–308
Request Response MEP, 308
SEI, 309
SOAP, 307–308
stateless session EJB as, 320–324
UDDI support, 66
WAR files
cross-server compatible, 316–317
deploying on Geronimo, 311–320
XML, 307–308
Web sites, Apache Software Foundation, 1
Web tier
components deployable, 56–57
Jetty, 58
Tomcat, 57–58
webservices.xml deployment descriptor
<handler> element, 315
introduction, 312
<port-component> element, 314
<service-impl-bean> element, 314
<webservices> element, 313
Web-tier applications
deploying
reference namespaces, 424
top-level elements, 424–425
EJBs, 243–244
Web-tier modules, external references, 244
web.xml deployment descriptor, 315–316
workmanager item Resource Adapter plan, 284
WSDL (Web Service Description Language), 307 , 321
wsdl4j directory, 86


Previous Page
Next Page

Index

X

xa-transaction item Resource Adapter plan, 285
xerces directory, 86
XML
schema, J2EE deployment descriptors, 177
Web services, 307–308
xmlbeans directory, 86
xml-reference login configuration, LoginModules, 363–367
xpp3 directory, 86
xstream directory, 86


List of Figures

Chapter 1: Getting Started with Geronimo

Figure 1-1: Geronimo project home page
Figure 1-2: Geronimo download page
Figure 1-3: Startup screen for server10
Figure 1-4: Output from list-modules command

Chapter 2: Basic Geronimo Configuration

Figure 2-1: The operations of the progeron application
Figure 2-2: Inside the progeron.ear file
Figure 2-3: Components inside progeron.ear are deployed to different servers
Figure 2-4: Geronimo Web console login page
Figure 2-5: The progeron.ear application deployed and running on Geronimo
Figure 2-6: Installing the progeron.ear application via the Web console
Figure 2-7: Confirming the installation and running of Application EARs
Figure 2-8: The list of modules currently deployed on the server
Figure 2-9: The lifecycle of a Geronimo-managed module
Figure 2-10: Configurable attributes for TomcatWebConnector listener component

Chapter 3: Apache and Geronimo

Figure 3-1: Homepage of the Apache Software Foundation
Figure 3-2: Organization of projects at the Apache Software Foundation
Figure 3-3: Historical timeline of major events associated with the Geronimo project

Chapter 4: Geronimo’s J2EE 1.4 Components

Figure 4-1: J2EE tiers and container services in Geronimo
Figure 4-2: User access Geronimo through the Web tier
Figure 4-3: EJBs deployable at Geronimo’s business tier
Figure 4-4: Geronimo’s JCA 1.5 and EIS tier services
Figure 4-5: Geronimo support for incoming Web service clients
Figure 4-6: Geronimo support for component access to external Web services
Figure 4-7: Geronimo’s CORBA interoperation support
Figure 4-8: Geronimo’s client application container
Figure 4-9: Naming service support in Geronimo

Chapter 5: Geronimo Architecture and Directory Structure

Figure 5-1: Running Geronimo server comprises GBeans and a kernel
Figure 5-2: Geronimo kernel configuration management service
Figure 5-3: Configuration management in Geronimo
Figure 5-4: Storing deployed modules binaries within the repository

Chapter 6: The Geronimo Deployer

Figure 6-1: Geronimo run-time deployer
Figure 6-2: The interoperable JSR-88-compliant components
Figure 6-3: Online deployment versus offline installation
Figure 6-4: Using the Web console to display module run-time state

Chapter 7: Using the Geronimo Debug Console and jconsole

Figure 7-1: JMX levels
Figure 7-2: JMX Agent level
Figure 7-3: Operations of an MEJB in a JSR-77 server such as Geronimo
Figure 7-4: Geronimo debug console is a JSR-77 client application
Figure 7-5: State transitions and JSR-77 manageable states
Figure 7-6: Debug console configuration started in Geronimo console
Figure 7-7: jconsole local running JVM section dialog
Figure 7-8: A successful connection to the Geronimo JVM
Figure 7-9: Initial display of the debug console
Figure 7-10: Querying for deployed application components by using a domain filter
Figure 7-11: jconsole display of Geronimo MBeans
Figure 7-12: Debug console query results for objects in the progeron application
Figure 7-13: Objects in the progeron application in jconsole
Figure 7-14: Debug console displaying the MBean attributes for the AuthorEJB session bean
Figure 7-15: jconsole displaying details for the AuthorEJB session bean

Chapter 8: Geronimo Web Console

Figure 8-1: Logging on to the Geronimo Web console
Figure 8-2: Real-time system information display
Figure 8-3: Viewing and searching logs with Geronimo Web console
Figure 8-4: The Server Manager portlet for system shutdown
Figure 8-5: Configuration of Web server connectors with Web console
Figure 8-6: The statistics shown by the Web Server Manager portlet
Figure 8-7: Web Server Network connectors configuration possibilities
Figure 8-8: Configuring ActiveMQ message broker and connectors with Geronimo Web console
Figure 8-9: Thread Pool Configuration portlet and available thread pools
Figure 8-10: Use the Apache mod_jk Configuration Portlet to expose the application
Figure 8-11: Directory hierarchy of the Geronimo repository
Figure 8-12: The Repository Viewer and Installation portlet
Figure 8-13: The Database Pools configuration portlet
Figure 8-14: Creating JMS resource groups
Figure 8-15: The Install New Application portlet
Figure 8-16: Portlet showing all the installed enterprise application EAR modules
Figure 8-17: Creating, installing, and removing plug-ins
Figure 8-18: Creating a new security realm with the Security Realms Portlet
Figure 8-19: Using the Keystore Configuration portlet
Figure 8-20: Running SQL against the embedded database with Database Manager portlet

Chapter 9: Geronimo Deployment Plans

Figure 9-1: Deployment descriptors and deployment plans for modules’ deployment
Figure 9-2: Deployed modules stored in the repository

Chapter 10: Web Container Configuration and Jetty

Figure 10-1: Default welcome screen for Web container
Figure 10-2: Network Listeners portlet
Figure 10-3: Network Listeners portlet for setting up HTTP
Figure 10-4: Network Listeners portlet for setting up HTTPS
Figure 10-5: Install New Applications portlet of the Web console
Figure 10-6: Installed Web Applications portlet of the Web console
Figure 10-7: geronimo-web XML Schemas (XSD) for Generic, Jetty, and Tomcat

Chapter 11: Tomcat Web Container Configuration

Figure 11-1: Geronimo/Tomcat Welcome Screen
Figure 11-2: Tomcat/Geronimo object hierarchy

Chapter 12: Deploying Enterprise Applications (EAR) with OpenEJB

Figure 12-1: Web-tier module references to business-tier EJBs and other resources
Figure 12-2: Business-tier references to separately deployed EJBs and other resources
Figure 12-3: Resolved EJB references within an EAR module
Figure 12-4: Mapping external EJB references via a Geronimo-specific deployment plan
Figure 12-5: Creating the wroxauthors database for the CMP bean
Figure 12-6: Creating and populating tables in the wroxauthors database
Figure 12-7: Viewing the content of the authors table in the Derby wroxauthors database
Figure 12-8: Using the wizard to create the AuthorConnectionsPool database pool
Figure 12-9: Setting driver and parameters for the AuthorConnectionsPool
Figure 12-10: Displaying the deployment plan for the deployment of AuthorConnectionsPool
Figure 12-11: Successful deployment of the AuthorConnectionsPool
Figure 12-12: The example running with data from Derby RDBMS
Figure 12-13: The Geronimo application client container

Chapter 13: Configuring and Deploying JDBC Resources with PostgreSQL

Figure 13-1: PostgreSQL architecture
Figure 13-2: Geronimo console display of deployed J2EE resource adapters
Figure 13-3: The beginning of the Database Pools Wizard
Figure 13-4: Step 1 of the Database Pools Wizard
Figure 13-5: Step 2 of the Database Pools Wizard
Figure 13-6: Select the appropriate JDBC driver to download
Figure 13-7: After downloading the JDBC driver and providing the required information
Figure 13-8: Completing the database pool configuration
Figure 13-9: Testing the JDBC connection
Figure 13-10: The database pool plan
Figure 13-11: The ProGeronimoPool
Figure 13-12: High-level architecture of Sequoia

Chapter 14: Deploying Web Services and CORBA Interoperation

Figure 14-1: Web service interactions
Figure 14-2: JAX-RPC simplifies coding of Java Web services and Web service clients
Figure 14-3: JAX-RPC interoperation with non-Java Web service clients
Figure 14-4: Geronimo server exposing application components as Web services
Figure 14-5: Deploying the Web service WAR using the Web console
Figure 14-6: Accessing the WSDL of the Web service using a browser
Figure 14-7: A successful run of the standalone Web service client
Figure 14-8: The AuthorBean EJB-based application
Figure 14-9: IDL compiler and programming-language-specific binding
Figure 14-10: CORBA ORB brokering a remote call
Figure 14-11: RMI-IIOP supporting both CORBA client access and RMI client access
Figure 14-12: The CORBA CSIv2 implementation

Chapter 15: Security

Figure 15-1: Security realm
Figure 15-2: JAAS Security GBean relationships
Figure 15-3: JaasLoginCoordinator proxying calls to LoginModules
Figure 15-4: The Geronimo console’s Security Realms portlet
Figure 15-5: Security Realm portlet Step 1
Figure 15-6: Security Realm portlet Step 2
Figure 15-7: Security Realm portlet Step 3
Figure 15-8: Security Realm portlet Step 4
Figure 15-9: Security Realm portlet Step 5
Figure 15-10: Security Realm-Show Deployment Plan screen

Chapter 16: Configuring, Deploying, and Using JMS Resources with Apache ActiveMQ

Figure 16-1: A diagram of the ActiveMQ architecture
Figure 16-2: A listing of the system modules with the ActiveMQ module in a running state
Figure 16-3: A listing of the system modules with the ActiveMQ module in a stopped state
Figure 16-4: The JMS Server screen provides the ability to manage network listeners within ActiveMQ
Figure 16-5: Adding a jabber network listener
Figure 16-6: Verifying that the ProGeronimoTopic is deployed
Figure 16-7: Creating JMS Resources for ActiveMQ
Figure 16-8: Create either a connection factory or a destination
Figure 16-9: Determine the type of connection factory to create
Figure 16-10: Fill in the necessary metadata for the connection factory
Figure 16-11: The connection factory has been created
Figure 16-12: Adding a JMS queue
Figure 16-13: Naming the queue
Figure 16-14: The JMS queue has been created
Figure 16-15: Viewing the plan
Figure 16-16: The ProGeronimo JMS Resource Group deployed

Appendix B: Run-Time Deployer Command Reference

Figure B-1: Using the Web console to deploy modules


List of Tables

Chapter 1: Getting Started with Geronimo

Table 1-1: Geronimo Builds
Table 1-2: Available Geronimo Releases
Table 1-3: Core J2EE Services Started by Geronimo

Chapter 2: Basic Geronimo Configuration

Table 2-1: Deployment Information Provided by the Deployer Tool
Table 2-2: Geronimo Application Components and Associated Deployment Packaging
Table 2-3: Standard Deployment Descriptors
Table 2-4: Geronimo-Specific Deployment Plans
Table 2-5: Geronimo Module Lifecycle States

Chapter 3: Apache and Geronimo

Table 3-1: Significant Events on the Geronimo Project Timeline

Chapter 4: Geronimo’s J2EE 1.4 Components

Table 4-1: Geronimo Web Services Support

Chapter 5: Geronimo Architecture and Directory Structure

Table 5-1: Assembly versus Modules
Table 5-2: Contents of the bin Directory
Table 5-3: Library Binaries Used by the Geronimo System
Table 5-4: Content of the endorsed libraries Subdirectory
Table 5-5: Format of Artifact Storage in the Repository
Table 5-6: Top-Level Directories of the Geronimo Repository
Table 5-7: Configuration Files under the META-INF Directory of a CAR Artifact
Table 5-8: Content of the schemas Directory
Table 5-9: The var Working Directories

Chapter 6: The Geronimo Deployer

Table 6-1: General Options for Command-Line Deployer
Table 6-2: Commands That Work with Modules
Table 6-3: Commands That Supply Information
Table 6-4: Plug-In Support Command
Table 6-5: Functional Elements Available in the Geronimo Maven Deployment Plug-In

Chapter 7: Using the Geronimo Debug Console and jconsole

Table 7-1: Mandatory Keys in the JSR-77 Object Name
Table 7-2: J2EE Types of Mandatory Parent Keys
Table 7-3: Geronimo’s JSR-77 Domains

Chapter 8: Geronimo Web Console

Table 8-1: Log Manager Attributes
Table 8-2: Web Server Connectors
Table 8-3: Module Types and Content

Chapter 9: Geronimo Deployment Plans

Table 9-1: Standard J2EE Deployment Descriptors
Table 9-2: XML Schema for Each of the J2EE Deployment Descriptors
Table 9-3: Location and Name of Plans Placed Inside Deployed Module
Table 9-4: XML Schema for Geronimo-Specific Deployment Plans

Chapter 10: Web Container Configuration and Jetty

Table 10-1: <web-app> Namespaces and Their Versions
Table 10-2: Container Configuration Namespaces
Table 10-3: Common Elements
Table 10-4: The JettyContainerImpl GBean
Table 10-5: The HTTPConnector GBean
Table 10-6: The HTTPSConnector GBean
Table 10-7: The AJP13Connector GBean
Table 10-8: The NCSARequestLog logger GBean

Chapter 11: Tomcat Web Container Configuration

Table 11-1: Tomcat Configuration Files and Their Geronimo Equivalents
Table 11-2: Tomcat GBeans
Table 11-3: geronimo-web.xml Plan Tomcat-Specific Elements and Parameters

Chapter 12: Deploying Enterprise Applications (EAR) with OpenEJB

Table 12-1: J2EE Descriptors and Associated Geronimo Deployment Plan
Table 12-2: Software Components in the Deployment Example
Table 12-3: The <enterprise-beans> Element in ejb-jar.xml
Table 12-4: Common Elements for Session Beans and EJB
Table 12-5: Session Bean Elements
Table 12-6: Entity Bean Elements
Table 12-7: Message Driven Bean (MDB) Elements
Table 12-8: <assembly-description> Subelements
Table 12-9: The openejb-jar.xml Deployment Plan
Table 12-10: EJB Reference Resolution in Geronimo
Table 12-11: J2EE Transaction Attributes for EJBs

Chapter 13: Configuring and Deploying JDBC Resources with PostgreSQL

Table 13-1: The RAR File Contents
Table 13-2: Allowed Content of a Resource Adapter Plan
Table 13-3: Contents of the TranQL Embedded Resource Adapter Configured for Derby
Table 13-4: A Deployment Plan for PostgreSQL
Table 13-5: The First Available Options When Creating a Database Pool
Table 13-6: More Available Options When Creating a Database Pool
Table 13-7: The Final Pool Configuration Options

Chapter 14: Deploying Web Services and CORBA Interoperation

Table 14-1: Java Classes in the Servlet Web Service Example
Table 14-2: Inside the <webservice> Element
Table 14-3: Subelements of the <port-component> Element
Table 14-4: Details of <service-impl-bean>
Table 14-5: Content from the <handler> Element
Table 14-6: The <service-ref> External Web Service Reference
Table 14-7: Java Classes Added to EJB to Support Its Exposure As Web Service
Table 14-8: CSIv2 TSS GBean Available in Geronimo 1.1
Table 14-9: CSIv2 CSS GBean Available in Geronimo 1.1

Chapter 15: Security

Table 15-1: DirectConfigurationEntry GBean
Table 15-2: ServerRealmConfigurationEntry GBean
Table 15-3: GenericSecurityRealm GBean
Table 15-4: LoginModuleGBean GBean
Table 15-5: JaasLoginModuleUse GBean
Table 15-6: Geronimo-Included LoginModules
Table 15-7: The <default-principal> Element
Table 15-8: The <distinguished-name> Element
Table 15-9: The <login-domain-principal> Element
Table 15-10: The <named-username-password-credential> Element
Table 15-11: The <principal> Element
Table 15-12: The <realm -principal> Element
Table 15-13: The <role> Element
Table 15-14: The <role-mapping> Element
Table 15-15: The <security> Element
Table 15-16: SecurityService GBean

Chapter 16: Configuring, Deploying, and Using JMS Resources with Apache ActiveMQ

Table 16-1: Overview of the ActiveMQ Broker Plan
Table 16-2: The RAR File Contents
Table 16-3: Allowed Content of a Resource Adapter Plan
Table 16-4: Breakdown of the Contents of the ActiveMQ Resource Adapter
Table 16-5: Available Options When Creating a JMS Resource Group
Table 16-6: Available Options When Configuring the Connection Factory
Table 16-7: Configuring the Destination

Appendix A: Geronimo Deployment Plans Cross-Reference

Table A-1: Geronimo-Specific Deployment Plans in This Appendix
Table A-2: Location and Name of XML Schema for Web-Tier Application Deployment plan
Table A-3: Top-Level Elements of geronimo-web.xml
Table A-4: Location and Name of XML Schema for Business-Tier EJB JAR Deployment Plan
Table A-5: Top-Level Elements of openejb-jar.xml
Table A-6: Location and Name of XML Schema for EIS-Tier Resource Adapter JAR Deployment Plan
Table A-7: Top-Level Elements of geronimo-ra.xml
Table A-8: The <adminobject> Element
Table A-9: Location and Name of XML Schema for the Enterprise Application Deployment Plan
Table A-10: Top-Level Elements of geronimo-application-client.xml
Table A-11: Location and Name of XML Schema for the Application Client Deployment Plan
Table A-12: Top-Level Elements of geronimo-application-client.xml
Table A-13: XML Schemas of Standard J2EE Deployment Descriptor


List of Listings

Chapter 10: Web Container Configuration and Jetty

Listing 10-1: config.xml Snippet of the Tomcat Container Configuration
Listing 10-2: config.xml Snippet Jetty Container Configuration
Listing 10-3: Example Generic geronimo-web.xml Descriptor with Tomcat- and Jetty-Specific Attributes

Chapter 11: Tomcat Web Container Configuration

Listing 11-1: Tomcat’s server.xml Skeleton File Layout
Listing 11-2: Geronimo’s Tomcat Configuration plan.xml Snippet
Listing 11-3: Example Connector Configurations
Listing 11-4: Geronimo’s HostGBean Example Declaration
Listing 11-5: Example Host and Valve Chain Declaration
Listing 11-6: Example JAAS Realm Configuration for an EngineGBean
Listing 11-7: Example geronimo-web.xml with Tomcat-Specific Attributes and GBeans

Chapter 13: Configuring and Deploying JDBC Resources with PostgreSQL

Listing 13-1: The Contents of the tranql-connector-derby-embed-xa-1.1.rar File
Listing 13-2: The system-database Deployment Plan
Listing 13-3: A deployment Plan for PostgreSQL
Listing 13-4: Output from the Deployment of postgresql-plan.xml
Listing 13-5: The Clustered PostgreSQL Deployment Plan
Listing 13-6: The postgresql-raidbl1-distributin-1.xml Sequoia Configuration File
Listing 13-7: The postgresql-raidb1-distribution-1.xml Sequoia Configuration File

Chapter 15: Security

Listing 15-1: Example Realm Configuration of a geronimo-properties-realm
Listing 15-2: Example Realm Configuration Using an xml-reference
Listing 15-3: Login-config XML Schema
Listing 15-4: geronimo-security-1.1 XML Schema

Chapter 16: Configuring, Deploying, and Using JMS Resources with Apache ActiveMQ

Listing 16-1: The ActiveMQ Broker Plan
Listing 16-2: The Contents of the activemq-rar-1.1.rar File
Listing 16-3: The ActiveMQ Resource Adapter Deployment Plan
Listing 16-4: Adding a New JMS Topic to the Plan