Develop Java EE 5 applications on Geronimo quickly and easily
Vamsavardhana Reddy Chillakuru Manu T. George
BIRMINGHAM - MUMBAI
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews. Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the authors, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book. Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.
First published: November 2009
Production Reference: 1061109
Published by Packt Publishing Ltd. 32 Lincoln Road Olton Birmingham, B27 6PA, UK. ISBN 978-1-847196-94-1 www.packtpub.com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Credits Authors
Editorial Team Leader
Vamsavardhana Reddy Chillakuru
Akshara Aware
Manu T. George Project Team Leader Lata Basantani
Reviewer Sujit Pal
Project Coordinator Rajashree Hamine
Acquisition Editor Rashmi Phadnis
Proofreader Development Editor
Dirk Manuel
Darshana D. Shinde Graphics Technical Editor
Nilesh Mohite
Mayuri Kokate Production Coordinator Copy Editor
Aparna Bhagat
Leonard D'Silva Cover Work Indexer
Aparna Bhagat
Monica Ajmera
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
About the Authors Vamsavardhana Reddy Chillakuru, a.k.a. Vamsi, is an Advisory Software
Engineer who has been working with IBM India Private Limited since 1996, and is part of the IBM worldwide Level 3 support team for Apache Geronimo and IBM WebSphere Application Server Community Edition (WASCE). He is proficient in Java and Java EE technologies, having more than 13 years experience in the IT Industry. His interests include application security in general, and cryptographic security in particular. He has presented sessions Apache conferences on various Apache Geronimo topics, ranging from security to server administration. He has authored many articles within IBM on developerWorks, and has also co-authored an IBM Redbook on Migration from WASCE to WebSphere Application Server (WAS). Considered as a security expert in the Geronimo community, he is actively involved in adding new security features to Geronimo. Associated with the Apache Geronimo project since July 2005, he is a committer on Apache Geronimo and Apache Tuscany projects, and is a member of the Apache Geronimo PMC. He is involved in the standards development for Service Component Architecture (SCA) and is a member of the OASIS (Organization for the Advancement of Structured Information Standards) SCA-Assembly, SCA-Java, and SCA-Policy Technical Committees, and the SCA-J Java EE Subcommittee. He received his B.Stat. (Hons.) and M.Stat. degrees from the Indian Statistical Institute, Kolkata, India in 1994 and 1996 respectively. I thank my wife Sushma and my son Susanth for their support throughout this book project. I thank my manager Sriram Mahalingam and director Kalpana Margabandhu at IBM India Private Limited for facilitating my authorship of this book. I thank my co-author Manu for his cooperation and the grace with which he handled the project. I thank the Apache Geronimo community for their support in my proficiency development with Geronimo. Finally, I am grateful to Packt Publishing for giving me this opportunity to author this book and thank Kshipra Singh, Rashmi Phadnis, Rajashree Hamine, Darshana Shinde, and Mayuri Kokate at Packt Publishing for their valuable support time and again.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Manu T. George is a Staff Software Engineer at IBM India Software Labs in Bangalore, India. He has eight years of experience in the IT field, most of it in Java and J2EE technologies. He is a committer on the Apache Geronimo and Apache OpenEJB projects, and has been a part of the IBM WebSphere Application Server Community Edition Level 3 Support Team for the past three years. He has been with IBM for around five years. Prior to that, he was an employee of Cognizant Technology Solutions India Ltd., and has worked on many services engagements there. His interests include Application Servers, especially in relation to Scalability, Transaction processing, EIS connectivity, and The Java Virtual Machine. He has also authored articles in IBM developer works, and has co-authored an IBM Redbook on Migration to WebSphere Application Server. He received his Bachelor of Technology in Applied Electronics from the College of Engineering Thiruvananthapuram in 2001. I am very grateful to my employer IBM, manager Sriram Mahalingam, and Director Kalpana Margabandhu for supporting me in writing this book and to Packt Publishing for giving me this opportunity. I would like to thank all the Packt staff that worked with us on this book. I would also like to thank my family, and especially my wife Nitya for the support that she provided and for her patience with me when I was authoring this book. I would like to thank both the Apache Geronimo and Apache OpenEJB communities for the support and help they gave me in understanding their respective projects. I would also like to mention my deep gratitude to David Blevins of Apache OpenEJB whose guidance and help both technical and non technical, was instrumental in helping me learn and understand the internals of OpenEJB as well as EJB technology. Finally, I would like to thank Vamsi, my co-author, for giving me the opportunity to work with him on this book.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
About the Reviewer Sujit Pal started programming some 20 years ago, and has never looked back
since. He currently works at Healthline Networks, Inc., a search vertically focused on health, as part of its Research and Development team. Apart from his work, his favorite pastime is to explore new software technologies, techniques, and languages, and he writes about his experiments at sujitpal.blogspot.com.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Table of Contents Preface Chapter 1: Getting Started with Geronimo
1 7
Motivation behind the Geronimo project Constituent projects Apache Geronimo architecture Downloading and running Apache Geronimo Geronimo Administration Console
7 8 11 12 14
Building Geronimo Contributing to Geronimo Java EE 5 development tools Java EE 5 samples Summary
18 20 20 20 21
Information portlet Java System Info portlet Server Logs portlet Web Server portlet JMS Server portlet Repository portlet JMS Resources portlet Database Pools portlet Deploy New portlet Plan Creator portlet Plugins portlet Applications portlets Users and Groups portlet DB Info portlet DB Manager portlet
Chapter 2: Geronimo Architecture
Inversion of Control and dependency injection GBeans Configurations
15 15 15 16 16 16 16 16 16 17 17 17 17 18 18
23
24 28 30
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Table of Contents
Dependencies High-level architecture Class loader architecture Modifying default class loading behavior Important modules Server directory structure Deployment architecture Deployer Repository Configuration builder Module builder Module builder extension Naming builder Hot deployment Deployment watcher Plugins Plugin catalog and plugin repository Custom server assemblies Extensible Administration Console Summary
Chapter 3: Database Connectivity
Database pool scopes Creating a server-wide database pool Using the Administration Console Wizard Installing unlisted drivers
Using the Deploy New portlet Using the command-line deployer Using GShell Creating an application-scoped database pool Creating a client-scoped pool Editing an existing pool Importing a pool from another application server Creating an XA pool Using a database pool in an application Accessing a server-scoped database pool Accessing an application-scoped database pool from the same application Accessing an application-scoped database pool from a different application Summary
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Table of Contents
Chapter 4: JMS Connectivity
Message broker configuration GBean configuration Using the Administration Console JMS resource scopes Creating JMS resources Creating Server-wide JMS resources Using the Administration Console Wizard Using the Deploy New portlet Using the command-line deployer Using GShell
Creating application-scoped JMS resources Creating application client-scoped JMS resources Using JMS resources in an application Connecting to a different provider Summary
Chapter 5: Java EE Application Deployment Deployment of applications Deployment descriptors Deployment plans The deploy tool Deployment from the Administration Console Deployment through GShell Web modules Servlet Filter Listener Web deployment descriptor Annotations Resource annotation EJB annotation
75
75 76 78 78 78 79
79 86 86 86
86 89 90 94 94
95
96 96 97 98 100 100 100 100 101 102 105 106
106 107
Web deployment plan
108
Sample web application EJB applications Annotations EJB deployment plan Sample EJB application
112 112 113 116 118
Tomcat specific configuration Jetty specific configuration
110 111
Deploy the JMS resources Deploy the EJB sample Deploy the Web application
120 120 120
[ iii ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Setting transaction timeout Transaction isolation levels Transactions in web applications
145 145 146
Summary
148
Chapter 6: Security
Overview of security standards Java Authentication and Authorization Service (JAAS) Java Authorization Contract for Containers (JACC) The Common Secure Interoperability Version 2 (CSIv2) protocol Securing the server directory Securing the Administration Console, JMX server, and deployer Securing the embedded Derby database Updating database pools Cryptographic security Keystores Keystores portlet Creating a new keystore Viewing the contents of a keystore Adding a private key Adding a trusted certificate Deleting a private key or trusted certificate Changing a keystore password
149
149 150 150 150 150 151 152 153 154 154 155
156 156 157 158 159 159
[ iv ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Table of Contents Unlocking keystore for availability Unlocking a keystore for editing Locking a keystore for editing or availability View private key details Changing a Private Key password Generating CSR for a Private Key Importing the CA Reply for a Private Key
Preparing a keystore for use with SSL Certificate Authority portlet Protecting passwords HTTPS connectors Tomcat HTTPS connectors Jetty HTTPS connectors
159 160 160 161 161 161 162
162 164 164 164
165 166
JAAS login modules Login modules for authentication
Principal wrapping Application security Configuring web application security
180 180 180
Configuring EJB application security
185
Run-as and default subjects
192
Using the Security Realms portlet Security realm deployment plan
Running the sample web application
Defining security roles in the deployment descriptor Declaring method permissions in the deployment descriptor Using annotations to define roles and permissions Mapping principals to roles in the EJB deployment plan Running the EJB sample application Configuring entity bean security Credential store Configuring an application to use a credential store Configuring run-as and default subjects Running a sample EJB application with run-as Configuring message-driven bean security
174 179
185 185 186 188 189 190 191 192 193 194 195 196
[]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Table of Contents
Configuring EAR application security Application-scoped security realms Single sign-on (SSO) Replacing the default security realm Summary
Chapter 7: CORBA
CORBA concepts ORB Naming service Security services Support in Geronimo Exposing EJBs through CORBA Creating a Target Security Service (TSS) SSL Authentication mechanism Identity Tokens
196 196 196 197 197
199
199 199 199 200 200 200 200
202 203 204
Configuring EJB to use TSS Sample application exposing EJBs through CORBA Deploying and running the sample EJB application Referencing EJBs through CORBA Creating a Client Security Service (CSS)
205 205 209 209 209
Configuring the EJB reference to use CSS Sample web application accessing CORBA EJBs
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Table of Contents
Global JNDI Summary
228 229
Chapter 9: Geronimo Plugins
231
Chapter 10: Administration
249
Developing a plugin Creating a plugin project Installing a plugin Available plugins Pluggable Administration Console Architecture Developing an Administration Console extension Plugins portlet Custom server assemblies and server profiles Summary Administration Console Server portlets
231 232 236 237 237 238 238 243 245 247 249 251
Information portlet Java System Info portlet Server Logs portlet Shutdown portlet Web Server portlet Thread Pools portlet Apache HTTP portlet JMS Server portlet Monitoring portlet
Deploy New portlet System Modules portlet Web App WARs portlet EJB JARs portlet Application EARs portlet J2EE connectors portlet App Clients portlet Plan Creator portlet
255 256 256 256 256 257 257 257
DB Info portlet DB Manager portlet
258 258
JMX Viewer portlet LDAP Viewer portlet
260 261
[ vii ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Web Server administration HTTP connectors HTTPS connectors AJP connectors Web Server Logs JMS server administration JMS listeners Monitoring the server Adding a Server Adding a Graph Creating a new view GShell Starting and exiting GShell Getting help Supported commands Summary
Eclipse and the web tools framework Download and installation GEP download and installation Developing an application in GEP Deploying and running or debugging the application in Geronimo Summary WADI Updating deployment descriptor and deployment plan Load balancing with Apache web server Installing the Apache web server Web app in Geronimo served through Apache web server Apache HTTP portlet Accessing the sample app through Apache web server Running multiple server instances from a single installation Clustered Helloworld-cluster application Updating workers.properties Farming Cluster member configuration
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Table of Contents
Farm deployment Running a sample application with Farm deployment Summary
Chapter 13: Logging
Configuring Apache Geronimo logging Configuring application logging Using log4j
Logging to the geronimo.log file and the command console Logging to a separate log file Logging using the ApplicationLog4jConfigurationGBean
Using the Java Logging API Using the SLF4j logging adapter Summary
Chapter 14: Geronimo Internals
321 322 323
325
326 327 327
328 330 332
333 333 334
335
Services provided by Geronimo Kernel ServerInfo Configurations and deployment ConfigurationManager
335 335 337 338 339
EditableConfigurationManager
340
LocalAttributeManager ArtifactResolver Developing a new GBean GBean attributes
341 341 342 343
GBean references GBean operations GBean constructor GBean interface GBeanLifecycle Sample GBean MySampleGBean Deploying the GBean Testing the GBean with GBean web app sample Summary
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Table of Contents
Appendix B: Troubleshooting
367
Index
373
Server startup errors BindException IllegalArgumentException due to a wrong instance name InvalidConfigurationException Deployment errors MissingDependencyException XmlException—Invalid deployment descriptor DuplicateDeploymentException Runtime errors LoginException—No LoginModules configured
367 367 368 369 369 369 370 371 372 372
[]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Preface Apache Geronimo is an open source application server that is suitable for use on everything from development environments to enterprise-level deployments. Geronimo brings together the best-of-breed open source technologies to deliver full Java EE 5 compliance. Distributed under the ASL2.0 license, one of the most liberal open source licenses, Geronimo becomes an application server of choice for enterprises and solution vendors. This book provides the reader with a comprehensive reference to the Apache Geronimo Application Server from the Apache Server Foundation. The authors have provided a reference for the average Apache Geronimo user that provides the user with the steps required to configure anything and everything in Apache Geronimo. This book covers everything from where to download the server software to how to customize it using custom GBeans. After reading this book, the user will be familiar with most of the features of Apache Geronimo v2.1. This book provides samples that are relevant to each task being performed. The book provides an in-depth coverage of the Apache Geronimo internals, in order for the user to be able to write custom services on Geronimo. There is also coverage of the Geronimo plugin architecture and how to extend the server functionality through plugins. The authors have made the different configuration items available as self contained chapters that can be referred to independently of the other chapters, so that readers can go straight to whatever part of Geronimo they want to configure.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Preface
What this book covers
Chapter 1: Introduction - This chapter introduces the reader to the Apache Geronimo Application Server, lists the features that it provides, and the steps that the user has to follow in order to download, install, and start the server. Chapter 2: Architecture - This chapter gives a high-level overview of the Geronimo architecture. It introduces the reader to the concepts of GBeans, Geronimo Plugins, and the different subsystems of Geronimo. Chapter 3: Database connectivity - This chapter talks about Geronimo's database connectivity features. It lists the databases supported, and explains how to create database pools and establish connectivity with all of the supported databases using Geronimo. Chapter 4: JMS - This chapter details the messaging features that Geronimo provides, and guides the user through using the bundled JMS provider, ActiveMQ, to create and use JMS resources. Chapter 5: Java EE Application deployment - This chapter details the installation of different types of Java EE applications and modules and application clients. It guides users through writing deployment plans for these different Java EE artifacts. This chapter also covers the transaction support provided by Geronimo. Chapter 6: Security - This chapter takes the user through configuring security in order to secure the server environment and the applications running in Geronimo. Chapter 7: CORBA - This chapter covers configuring the EJBs running in Geronimo so that they are available through CORBA, and also covers configuring remote EJB references to invoke remote EJBs through CORBA. Chapter 8: JNDI - This chapter describes the different JNDI environments in Geronimo, gives the steps necessary to bind custom resources to JNDI by using GBeans, and shows us how the global JNDI environment can be leveraged for user's applications. Chapter 9: Plugins - This chapter educates the user in creating and deploying Geronimo plugins, creating custom server assemblies, and extending Administration Console through plugins. Chapter 10: Administration - This chapter walks the user through the common administration tasks, such as managing server components, application management, monitoring, working with keystores, and GShell.
[]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Preface
Chapter 11: Eclipse Plugin - This chapter introduces the Geronimo Eclipse Plugin (GEP) and explains how to obtain and install it. It takes the user through the various features of the GEP and shows how to develop a sample application by using the Geronimo Eclipse Plugin. Chapter 12: Clustering - This chapter covers how to configure horizontal and vertical clustering using Geronimo, demonstrates web application clustering using WADI, and explains how to configure load balancing by using the Apache Web Server and mod_jk plugin. Chapter 13: Logging - This chapter covers all of the configurations required for setting up logging for both the server and user applications. It covers logging frameworks such as log4j JUL, and so on, and the SLF4j wrapper that comes with Geronimo. Chapter 14: Geronimo Internals – This chapter introduces the user to the internals of Geronimo and the low-level services such as kernel, server info, configuration manager, and so on. It takes the user through developing and deploying new services through GBeans. Appendix-A: Deployment plans – This appendix covers elements common to all Geronimo deployment plans. Appendix-B: Troubleshooting – This appendix covers troubleshooting server startup, application deployment, application startup, and runtime problems.
What you need for this book
The reader must be familiar with Java EE 5 concepts and application development.
Who this book is for
This book is intended for Java EE developers and server administrators who would like to use Geronimo for developing and deploying fully-fledged Java EE 5 applications, and Independent Solution Vendors who want to freely distribute Geronimo with their solutions.
[]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Preface
Conventions
In this book, you will find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning. Code words in text are shown as follows: "In the given sample code, you see that there is a new class called the Assembler." A block of code is set as follows:
Nitya
When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:
console.dbpool DerbyTestPool
Any command-line input or output is written as follows: java –cp di-sample-1.0.jar packtsamples.Assembler packtsamples. di.ServiceTaxCalculator
New terms and important words are shown in bold. Words that you see on the screen, in menus or dialog boxes for example, appear in the text like this: "Deployment can also be done by using the Deploy New portlet in the Administration Console". Warnings or important notes appear in a box like this.
Tips and tricks appear like this.
[]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Preface
Reader feedback
Feedback from our readers is always welcome. Let us know what you think about this book—what you liked or may have disliked. Reader feedback is important for us to develop titles that you really get the most out of. To send us general feedback, simply send an email to [email protected], and mention the book title in the subject of your message. If there is a book that you need and would like to see us publish, please send us a note in the SUGGEST A TITLE form on www.packtpub.com, or send an email to [email protected]. If there is a topic that you have expertise in and you are interested in either writing or contributing to a book on, see our author guide at www.packtpub.com/authors.
Customer support
Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase. Downloading the example code for the book Visit http://www.packtpub.com/files/code/6941_Code.zip to directly download the example code. The downloadable files contain instructions on how to use them.
Errata
Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code—we would be grateful if you would report this to us. By doing so, you can save other readers from frustration, and help us to improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/support, selecting your book, clicking on the let us know link, and entering the details of your errata. Once your errata are verified, your submission will be accepted and the errata added to any list of existing errata. Any existing errata can be viewed by selecting your title from http://www.packtpub.com/support.
[]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Preface
Piracy
Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works, in any form, on the Internet, please provide us with the location address or web site name immediately so that we can pursue a remedy. Please contact us at [email protected] with a link to the suspected pirated material. We appreciate your help in protecting our authors, and our ability to bring you valuable content.
Questions
You can contact us at [email protected] if you are having a problem with any aspect of the book, and we will do our best to address it.
[]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Getting Started with Geronimo Apache Geronimo is a free, open source Java EE application server from the Apache Software Foundation (ASF). The latest released version, 2.1.4, is Java EE 5 certified. In this chapter, we will quickly take you through: •
The motivation behind the Geronimo project
•
Geronimo architecture
•
The constituent projects that it integrates
•
Downloading and running Geronimo
•
Building Geronimo from source code
•
Contributing to the Geronimo project
This should get you started with using the Geronimo application server right away, and give you a glimpse of what Geronimo has to offer.
Motivation behind the Geronimo project
Apache Geronimo started as an application server. The first release of Apache Geronimo, that is, version 1.0 was J2EE 1.4 certified. The latest version is backward compatible to the J2EE 1.4, 1.3, and 1.2 specifications. The rationale behind Apache Software Foundation creating this project was: •
There was no open source J2EE server based on BSD license available in the market at the time Apache Geronimo was proposed. With BSD license, anyone could modify the source code and also include it in their derivative offerings without making the derivative open source.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Getting Started with Geronimo
•
There were many projects in the Apache Software Foundation that implemented parts of the J2EE specification. The rationale was to create a full application server that used these best-of-breed open source components internally and filled in the gaps that were missing.
•
There was still more room for innovation in the J2EE application server space.
Thus Apache Geronimo was born.
Constituent projects
As the aim was to integrate many existing Apache projects into Apache Geronimo, the server had a very modular architecture with a lightweight and compact kernel into which other services could be plugged in order to provide additional functionality. Other containers that implemented parts of the J2EE specifications could then be added on top of this, and they would be able to use the services that were available. The various components and services could be stopped when they were not required, to save on system resources. In newer versions, this was improved upon and you could install or uninstall plugins at runtime to add or remove functionality. The latest version even has the ability to generate customserver assemblies from the Administration Console of the server. Apache Geronimo leverages a lot of popular open source projects to provide Java EE 5 compliance. Some of the projects used are: •
Apache Tomcat Apache Tomcat is an open source JavaServer Pages (JSP) and Java Servlet container from the Apache Software Foundation. It is fast, lightweight, and very popular, and is used widely in the industry. It is considered as a benchmark for Servlet and JSP containers. Apache Tomcat is used by Apache Geronimo as its web container. It is thereby used to host the web applications that you deploy in Apache Geronimo. Apache Tomcat is hosted at http://tomcat.apache.org.
•
Apache OpenEJB Enterprise JavaBeans (EJB) technology provides the server-side component architecture for Java Platform. EJB technology enables the rapid and simplified development of distributed, transactional, secure, and portable applications based on Java technology.
[]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 1
Apache OpenEJB is a free, open source EJB container. It is both embeddable and lightweight. The current version, OpenEJB 3.x, supports EJB 3.0 and is also backward compatible with previous EJB versions. It also has a few experimental EJB 3.1 features. Apache OpenEJB is used by Apache Geronimo as its EJB container. Therefore, all EJB applications that you deploy in Apache Geronimo will in turn be deployed into Apache OpenEJB by the deployment subsystem. Apache OpenEJB is a complete rewrite of OpenEJB 2.1, which was included in Apache Geronimo 1.x. Thus, it is more robust and has a higher order of performance than its predecessor. Apache OpenEJB can be made to work with different JPA providers. However, it provides Container Managed Persistence (CMP) of EJB 2.1 support, through a wrapper over OpenJPA. Apache OpenEJB is hosted at http://openejb.apache.org. •
Apache Axis 1.x Apache Axis is an open source web services engine from the Apache Software Foundation. This version of Apache Axis is used to provide support for JAX-RPC web services. Apache Axis is hosted at http://ws.apache.org/axis.
•
Apache Axis2 Apache Axis2 is a rewrite of the Apache Axis web services engine. Apache Axis2 is used to provide support for JAX-WS, SOAP 1.2, SAAJ, and all the other specifications of web services, which are required for Java EE 5 compliance. Apache Axis2 is hosted at http://ws.apache.org/axis2/.
•
Apache CXF Apache CXF is an open source services framework. It is also available as the web services container in Geronimo. It can be used as an alternative to Apache Axis2. Apache CXF is hosted at http://cxf.apache.org.
•
Jetty from Mortbay Jetty is a fast and lightweight open source web server and Servlet container. It is easily embeddable and, like Tomcat, is widely used. Jetty can also be used as the web container in Apache Geronimo, as an alternative to Tomcat. This project is hosted at http://www.mortbay.org/jetty and is distributed under the Apache License, Version 2.0.
•
Apache ActiveMQ Apache ActiveMQ is a popular and powerful open source message broker. It is fast, lightweight, embeddable, and supports many cross language clients and protocols. It supports the JMS specification. It is used as a message broker in Apache Geronimo. Apache Geronimo 2.1.4 uses ActiveMQ 4.1.2. Apache ActiveMQ is hosted at http://activemq.apache.org.
[]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Getting Started with Geronimo
•
•
•
•
•
•
Apache XBean Apache XBean is a plugin-based server framework. It provides functionality to discover, download, and install server plugins from a remote repository. It also supports Inversion of Control (IoC), lifecycle and class loader management, JMX, and Spring Integration. Apache XBean is a subproject of the Apache Geronimo project, and is hosted at http://geronimo.apache.org/xbean/. Apache Derby Apache Derby is a free, open source, lightweight, and embeddable RDBMS, implemented entirely in Java. Derby is integrated in Apache Geronimo as the default database, and the Administration Console has built-in portlets for basic Apache Derby administration tasks. Apache Derby is a part of the Apache DB project, and is hosted at http://db.apache.org/derby. Apache Scout Apache Scout is an open source implementation of the Java API for XML Registries (JAXR). It provides a registry where web services can be registered by their providers, and users can look for the services they need in the registry. Apache Scout is hosted at http://ws.apache.org/scout/. Apache OpenJPA Apache OpenJPA is an open source Java Persistence API (JPA) container that can either be used as a standalone POJO persistence layer or integrated into any EJB 3.0 container. OpenJPA was donated by BEA to the Apache Software Foundation, and is based on BEA's Kodo JPA Engine. It is used as the default JPA provider for Apache Geronimo and Apache OpenEJB. The version used in Apache Geronimo 2.1.4 is OpenJPA 1.2. Apache OpenJPA is hosted at http://openjpa.apache.org/. Apache log4j & SLF4J Apache log4j is the logging framework that is used for logging in Apache Geronimo, and SLF4J is the logging adapter that is used so that the source is not tied down to any logging framework. Apache log4j is hosted at http:// logging.apache.org/, and SLF4J is hosted at http://www.slf4j.org/ Apache Commons The Commons is an Apache project focused on all aspects of reusable Java components. Some of the components are: ° BeanUtils: Easy-to-use wrappers around the Java reflection and introspection APIs ° FileUpload: A file upload capability for servlets and web applications ° IO: Collection of I/O utilities, and so on Apache Commons is hosted at http://commons.apache.org. [ 10 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 1
•
Apache GShell Apache GShell is a framework for building rich command-line applications. GShell is used as a bootstrap launcher for Apache Geronimo. It provides a number of built-in commands, and many optional ones. GShell is extensible, and the version in Apache Geronimo has been extended with many Apache Geronimo specific commands. Apache GShell is a subproject of the Apache Geronimo project, and is hosted at http://cwiki.apache.org/GSHELL.
•
Apache Yoko Apache Yoko is a robust and high-performance CORBA server written in Java that can run on any Java Virtual Machine (JVM). It provides the ORB and CORBA naming service that is used by Apache Geronimo. It is also used by Geronimo to expose EJBs as CORBA services. Apache Yoko is a subproject of the Apache Geronimo project, and is hosted at http://cwiki.apache.org/YOKO/.
•
TranQL TranQL is an open source framework for building persistence engines. The TranQL project is hosted at the Codehaus. It's also a framework for building J2CA connectors. TranQL provides J2CA connector implementations that wrap drivers for several popular relational databases. The TranQL project is hosted at http://tranql.codehaus.org.
These open source projects are plugged into the Geronimo system via wrapper GBeans or as dependant libraries. You can configure Geronimo servers that contain all or a subset of these projects. Apache Geronimo also provides you with more choice when choosing the parts that will make up your application server than any other application server. For example, you can have a server with Apache Tomcat as the web container and Axis2 as the web services container, or you can have a server with Jetty and CXF. So one key differentiator at the time Apache Geronimo was released was that it was not monolithic like many other Java EE application servers. However, most application server vendors are now re-architecting their servers to also be modular and lightweight.
Apache Geronimo architecture
Apache Geronimo consists of an IoC kernel that provides dependency management, configuration management, lifecycle management, and repository services. The plumbing required by Java EE containers, namely, support for deployment, transactions, remoting, naming, work management, and security, is implemented on top of the kernel. On top of this are plugged in the various containers, such as Apache OpenEJB, Apache ActiveMQ, and so on, which provide parts of the Java EE functionality and together make Geronimo a Java EE application server. [ 11 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Getting Started with Geronimo
GBeans are the basic building blocks of Geronimo. A GBean provides lifecycle callbacks and acts as a thin wrapper around the various containers and modules that are plugged into Geronimo. The kernel then manages these containers and modules via the GBeans that wrap them. A group of GBeans that wraps a particular module is called a configuration. Interestingly, a configuration itself is a GBean, thereby leading to the statement, "Everything in Geronimo is a GBean!!" The Geronimo architecture is modular and extensible. The extensibility is achieved via plugins. Geronimo provides the ability for new functionality to be added as plugins. Plugins are actually configurations or groups of configurations, along with metadata about their dependencies. Plugins can be installed in Geronimo via the Administration Console or via the command-line tools. Geronimo has the ability to download and install plugins from a remote repository. One such remote repository is available at http://geronimoplugins.com/. Thus, the Geronimo kernel also provides plugin installation and management services. Each of the containers in Geronimo is actually installed as a plugin. This method of extending the features of Geronimo via plugins initially gave rise to a minimal version of the server called little Geronimo (Little-G) that consisted of the Geronimo kernel, the required plumbing, and the web container. Later, even more flexibility was provided and you could export servers containing only the components you needed, from the Administration Console. This provided a large amount of flexibility in the configurations. A set of predefined server profiles were also provided out of the box, for users to export.
Downloading and running Apache Geronimo
Apache Geronimo can be downloaded from the project's web site at http://geronimo.apache.org. The Downloads section has the latest version as well as previous releases. The server is available for download in .zip and tar.gz formats. Download the ZIP file and then extract it to a directory on your drive. Let us refer to this directory as . Open a command window and change directory to /bin. Set either the JAVA_HOME or the JRE_HOME environment variable to a directory where Sun Java 1.5 is installed, and type start-server, in Windows, or ./start-server, in Linux. This will start the Geronimo server in the same command window. The following screenshot shows the command-line console output from Geronimo server startup:
[ 12 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 1
The console displays the port numbers on which the various services are running, a list of Started Application Modules, and the context-root for the running web applications. You can use startup to start Geronimo in a new window. If you want to start GShell (a Java-based shell for Geronimo), then you need to use gsh. Invoking the GShell results in a new shell prompt in the format user@hostname:/>, for example, administrator@foo:/>. GShell supports a large number of commands to perform a variety of operations in Geronimo. You can start or stop the server, install or uninstall applications, and even export a new server from the current installation. To get a list of commands that are supported by GShell, type help at the prompt. [ 13 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Getting Started with Geronimo
To start the server from GShell, type geronimo/start-server at the GShell prompt. To stop the server, open another GShell prompt and enter geronimo/stop-server. You will be prompted to enter the username and password. Enter system for the Username and manager for the Password. If you encounter any port conflicts during startup, you will need to either shut down the other services that are using those ports or you will need to configure the Geronimo installation to use other ports. The steps for doing this are given in Appendix-B, Troubleshooting.
Geronimo Administration Console
Geronimo has a powerful web-based Administration Console, consisting of portlets developed using Apache Pluto that can be used for various administrative tasks. The Administration Console provides a convenient and user friendly way to administer many aspects of the server. Once the Geronimo server has been started, the Administration Console can be accessed by using the URL http://localhost:8080/console. The default Username is system and the default Password is manager. The following figure shows the layout of the Administration Console.
[ 14 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 1
The portlets are grouped into various portlet groups, such as, Server, Services, Applications, Security, and so on, according to the functions addressed by the portlets. The portlets can be broadly divided into the following two categories: •
Portlets to monitor the server: Information portlet, Java System Info portlet, Monitoring portlet, Repository portlet, and DB Info portlet are some of the portlets that help monitor the server status.
•
Portlets to perform administrative operations: Web Server portlet, JMS Server portlet, Database Pools portlet, portlets under Applications group, and DB Manager portlet are some of the portlets that help in administering some aspect of the server.
In this section, we will briefly introduce some of the commonly-used portlets. See Chapter 10, Administration for more details on Administration Console.
Information portlet
The Information portlet is launched by clicking on the Information link under the Server portlet group in Console Navigation pane. This portlet displays information on the version number of the Geronimo server, the server Start Time, the server Up Time, the Name of the operating system, the JVM in which the server is running, and the current Server Memory Usage.
Java System Info portlet
The Java System Info portlet is launched by clicking on the Java System Info link under the Server portlet group in Console Navigation. This portlet displays the system properties set in the JVM in which the server is running. For display purposes, the system properties are grouped into Java, Virtual Machine, Operating System, Sun, User, and Etc groups.
Server Logs portlet
The Server Logs portlet is launched by clicking on the Server Logs link under the Server portlet group in Console Navigation. This portlet enables you to browse the server log messages, web access log messages, and Derby database log messages. The portlet provides the ability to filter the log messages based on various criteria, such as displaying log messages containing specified text, generated within a specific date range, and so on. The portlet also features a Log Manager, which allows the server log settings to be temporarily altered.
[ 15 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Getting Started with Geronimo
Web Server portlet
The Web Server portlet is launched by clicking on the Web Server link under the Server portlet group in Console Navigation. This portlet enables you to add new HTTP, HTTPS, and AJP ports or listeners to the web container, and perform Start, Stop, Restart, Edit, and Delete operations on existing listeners. In order to add a new HTTP port to the web container, click on Tomcat BIO HTTP Connector. On the next page, enter a uniqueName for the connector, change the default port number to a port number of your choice, and click on Save.
JMS Server portlet
The JMS Server portlet is launched by clicking on the JMS Server link under the Server portlet group in Console Navigation. This portlet enables you to add new JMS listeners and perform Start, Stop, Edit, and Delete operations on existing JMS listeners.
Repository portlet
The Repository portlet is launched by clicking on the Repository link under the Services portlet group in Console Navigation. This portlet displays a list of JAR files and configurations deployed on the server. The portlet also provides the ability to install a new archive into the server's repository.
JMS Resources portlet
The JMS Resources portlet is launched by clicking on the JMS Resources link under the Services portlet group in Console Navigation. This portlet enables you to create new JMS resources such as Connection Factory, Queue, and Topic.
Database Pools portlet
The Database Pools portlet is launched by clicking on the Database Pools link under the Services portlet group in Console Navigation. This portlet enables you to Create a new database pool: Using the Geronimo database pool wizard and to perform Edit and Delete operations on existing database pools. You can also Run SQL commands against an existing data source.
Deploy New portlet
The Deploy New portlet is launched by clicking on the Deploy New link under the Applications portlet group in Console Navigation. This portlet enables you to deploy a new application or a new service into the server. An archive or a Geronimo specific deployment plan, or both can be used to deploy new applications and services. [ 16 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 1
Plan Creator portlet
The Plan Creator portlet is launched by clicking on the Plan Creator link under the Applications portlet group in Console Navigation. This portlet enables creating a Geronimo specific deployment plan required to deploy an archive in a sequence of steps, and deploying the archive using the generated deployment plan.
Plugins portlet
The Plugins portlet is launched by clicking on the Plugins link under Applications portlet group in Console Navigation. This portlet provides the ability to install plugins onto a Geronimo server, export existing configurations as Geronimo plugins, and create a custom server assembly from configurations and plugins running in the server.
Applications portlets
The Applications portlets lets you view the running status of the applications, perform operations like Stop, Start, Restart, and Uninstall applications. There are multiple portlets for this purpose, each of which displays a selected group of configurations running on the server. The portlets that fall into this category are: •
Web App WARs portlet: Shows the web applications deployed on the server
•
System Modules portlet: Shows the services (such as ActiveMQ, Axis, and so on) deployed on the server
•
Application EARs portlet: Shows the enterprise applications deployed on the server
•
EJB JARs portlet: Shows the EJB applications deployed on the server
•
J2EE Connectors portlet: Shows the database pool and JMS resource configurations deployed on the server
•
App Clients portlet: Shows the enterprise application clients installed on the server
Users and Groups portlet
The Users and Groups portlet is launched by clicking on the Users and Groups link in the Security portlet group under Console Navigation. This portlet enables you to add new users, add new groups, change an existing user password, edit an existing group to change the user membership of the group, delete an existing user, and delete an existing group. Note that users belonging to the admin group have access to the Administration Console.
[ 17 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Getting Started with Geronimo
DB Info portlet
The DB Info portlet is launched by clicking on the DB Info link in the Embedded DB portlet group under Console Navigation. This portlet displays information on the embedded Derby database server.
DB Manager portlet
The DB Manager portlet is launched by clicking on the DB Manager link in the Embedded DB portlet group under Console Navigation. This portlet enables an administrator to create new databases, delete an existing database, run SQL commands against an existing database, view database tables, and browse the contents of database tables.
Building Geronimo
You can download the source code of Geronimo and build the server from it. The Geronimo source code is maintained in a Subversion repository. The URL is https://svn.apache.org/repos/asf/geronimo/server. There are different tags for the different releases. For example https://svn.apache.org/repos/ asf/geronimo/server/tags/2.1.4 corresponds to the 2.1.4 release. The branches are for making bug fixes to previous releases if required. The trunk is the latest codebase, where most of the new development is happening. You can check out and build any of these. We will now go through the procedure to download and check out the source code of version 2.1.4. Go to the location on your disk where you want to check out the code and type the following command: svn checkout https://svn.apache.org/repos/asf/geronimo/server/ tags/2.1.4 server
You need to install the Subversion client before you can actually checkout the code. The client is available at http://subversion.tigris.org/
Once the process has completed you will notice that a directory called server that contains the source is created. You will now need to download and install Apache Maven 2, which is required in order to build the server from the source code. You can download Maven 2 from http://maven.apache.org/download.html.
[ 18 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 1
You need to use Sun JDK 1.5.x and Apache Maven 2.0.9, to build Geronimo version 2.1.4 server from source code.
Once you finish installing Maven 2, you need to change your directory to the directory into which you checked out the source, and then run mvn install. The build process will take 30 to 40 minutes and you will need to be connected to the Internet during the build. Once the build is successful (all the tests need to pass for the build to succeed), you can find the various server distributions in the assemblies directory. In case there is a build failure, due to test failures you can run the builds with the -Dmaven.test.skip=true, -Dmaven.itest.skip=true
flags, so that test failures are ignored. The assemblies directory contains the following subdirectories: •
geronimo-boilerplate-minimal
Provides boilerplate files for all of the Geronimo server assemblies •
geronimo-framework
A Geronimo server framework assembly •
geronimo-jetty6-javaee5
Java EE 5 certified Geronimo version with Jetty as the web container and CXF as the web services engine, and all the bells and whistles •
geronimo-jetty6-minimal
Minimal version of Geronimo with just the web container (Jetty) and the Geronimo framework •
geronimo-tomcat6-javaee5
Java EE 5 certified Geronimo version with Tomcat as the web container and Axis2 as the web services engine and all the bells and whistles •
geronimo-tomcat6-minimal
Minimal version of Geronimo with just the web container (Tomcat) and the Geronimo framework
[ 19 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Getting Started with Geronimo
Contributing to Geronimo
Apache Geronimo is developed and distributed under the Apache License, Version 2.0, which is a derivative of the BSD License. This means that any individual or commercial entity can distribute Apache Geronimo for free. The big difference from GPL licensed software is that derivative works that are distributed need not be open source. This makes Geronimo attractive to corporations and software houses. Some corporations actually pay their employees to work full time on Geronimo. However, a lot of people contribute to Geronimo as a hobby or as a way to learn how to write scalable software. Anyone can contribute new features, raise defects, contribute documentation, or contribute bug fixes to Geronimo. This is encouraged, as a more vibrant community will help to make a better product. The procedure to follow is to open an issue in the Geronimo issue tracker (JIRA) and attach a patch file. You can generate the patch file by invoking the svn diff subcommand. Once you attach a patch file, one of the committers (people who can make changes to the source code in the Geronimo subversion repository) will review your patch and if he or she feels it is valid, will commit it to the source tree in subversion repository.
Java EE 5 development tools
Eclipse from the Eclipse Foundation is a popular open source IDE written in Java that supports a variety of languages, including Java. Support for Java EE 5 is provided by a set of Eclipse plugins called the Web Tools Platform or WTP. WTP provides extension points for application server vendors to extend WTP to integrate with their servers and provide deployment and debug functionality during server-side Java EE development. Apache Geronimo provides a WTP server adapter or an Eclipse plugin that runs on top of WTP and provides Java EE developers with features to develop, deploy, and debug Java EE applications on Apache Geronimo. The Geronimo Eclipse Plugin (GEP) can be downloaded from the subprojects site at http://geronimo.apache.org/development-tools.html. The source code for the Geronimo Eclipse Plugin is available from https://svn.apache.org/repos/asf/ geronimo/devtools/eclipse-plugin/.
Java EE 5 samples
Apache Geronimo provides a set of sample Java EE 5 applications that exercise almost all aspects of the Java EE 5 specification. These samples range from the most trivial web applications such as the Inventory sample to reasonably complex enterprise applications like the Day Trader. The samples for different versions of Apache Geronimo can be obtained from the URL http://cwiki.apache.org/GMOxSAMPLES/. [ 20 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 1
The Day Trader sample is actually checked into the subversion tree for Apache Geronimo. Users can download it from the Subversion repository and build it. The Subversion (SVN) URL is https://svn.apache.org/repos/asf/ geronimo/daytrader/. The other samples are also available in SVN at https://svn.apache.org/repos/
asf/geronimo/samples/.
Summary
In this chapter, we have provided an overview of Geronimo, various component projects in Geronimo, and we have briefly discussed the architecture of Geronimo. We have discussed how to download and run Geronimo, and given an introduction to the Administration Console. We have also provided instructions on how to build Geronimo from source code that has been checked out from the Geronimo Subversion repository.
[ 21 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture This chapter expands on what we discussed in the first chapter about the Apache Geronimo architecture. We will first see the concept of Inversion of Control (IoC) and dependency injection, which are two of the core concepts around which the current architecture is developed. We will then give a high-level overview of the internal architecture of Apache Geronimo and go through each component that makes up the architecture. Therefore, we will be covering GBeans, configurations, the kernel interface, repository, attribute store, dependencies, class loaders, deployment, plugins, and the concept of custom server assemblies. We will be covering these topics in detail so that you are able to understand the big picture. It will also help you if you want to contribute to Apache Geronimo or develop new services to run on Apache Geronimo. We will also list the different modules by their configuration IDs and map them to their functionality. In this chapter, you will learn about: •
How Inversion of Control and dependency injection work
•
GBeans—the building blocks of Geronimo
•
Configuration—a collection of GBeans deployed together
•
High-level architecture of Geronimo
•
Class loader architecture
•
Geronimo server directory structure
•
Deployment architecture
•
Plugins
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture
Inversion of Control and dependency injection
Inversion of Control (IoC) is a design pattern used in software engineering that facilitates the creation of loosely-coupled systems. In an IoC system, the flow of control is inverted, that is, the program is called by the framework—unlike in normal linear systems where the program calls the libraries. This allows us to circumvent the tight coupling that arises from the control being with the calling program. Dependency injection is a specific case of IoC where the framework provides an assembler or a configurator that provides the user program with the objects that it needs through injection. The user program declares dependencies on other services (provided by the framework or other user programs), and the assembler injects the dependencies into the user program wherever they are needed. It is important that you clearly understand the concept of dependency injection before we proceed further into the Geronimo architecture, as that is the core concept behind the functioning of the Geronimo kernel and how services are loosely coupled in it. To help you understand the concept more clearly, we will provide a simple example. Consider the following two classes: package packtsamples; public class RentCalculator{ private float rentRate; private TaxCalculator tCalc; public RentCalculator(float rate, float taxRate){ rentRate = rate; tCalc = new ServiceTaxCalculator(taxRate); } public void calculateRent(int noOfDays){ float totalRent = noOfDays * rentRate; float tax = tCalc.calculateTax(totalRent); totalRent = totalRent + tax; System.out.println("Rent is:"+totalRent); } } package packtsamples; public class ServiceTaxCalculator implements TaxCalculator{ private float taxRate; public ServiceTaxCalculator(float rate){ taxRate = rate; } public float calculateTax(float amount){ [ 24 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 2 return (amount * taxRate/100); } } package packtsamples; public interface TaxCalculator{ public float calculateTax(float amount); } package packtsamples; public class Main { /** * @param args. args[0] = taxRate, args[1] = rentRate, args[2] = noOfDays */ public static void main(String[] args) { RentCalculator rc = new RentCalculator(Float.parseFloat(args[1]), Float.parseFloat(args[0])); rc.calculateRent(Integer.parseInt(args[2])); } }
The RentCalculator class calculates the room rent including tax, given the rent rate, and the number of days. The TaxCalculator class calculates the tax on a particular amount, given the tax rate. As you can see from the code snippet given, the RentCalculator class is dependent on the TaxCalculator interface for calculating the tax. In the given sample, the ServiceTaxCalculator class is instantiated inside the RentCalculator class. This makes the two classes tightly coupled, so that we cannot use the RentCalculator with another TaxCalculator implementation. This problem can be solved through dependency injection. If we apply this concept to the previous classes, then the architecture will be slightly different. This is shown in the following code block: package packtsamples.di; public class RentCalculator{ private float rentRate; private TaxCalculator tCalc; public RentCalculator(float rate, TaxCalculator tCalc){ rentRate = rate; this.tCalc = tCalc; } public void calculateRent(int noOfDays){ float totalRent = noOfDays * rentRate; float tax = tCalc.calculateTax(totalRent); totalRent = totalRent + tax; System.out.println("Rent is:" +totalRent); } [ 25 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture } package packtsamples.di; public class ServiceTaxCalculator implements TaxCalculator{ private float taxRate; public ServiceTaxCalculator(float rate){ taxRate = rate; } public float calculateTax(float amount){ return (amount * taxRate/100); } } package packtsamples.di; public interface TaxCalculator{ public float calculateTax(float amount); }
Notice the difference here from the previous implementation. The RentCalculator class has a TaxCalculator argument in its constructor. The RentCalculator then uses this TaxCalculator instance to calculate tax by calling the calculateTax method. You can pass in any implementation, and its calculateTax method will be called. In the following section, we will see how to write the class that will assemble this sample into a working program. package packtsamples.di; import java.lang.reflect.InvocationTargetException; public class Assembler { private TaxCalculator createTaxCalculator(String className, float taxRate){ TaxCalculator tc = null; try { Class cls = Class.forName(className); tc = (TaxCalculator)cls.getConstructors()[0] .newInstance(taxRate); } catch (ClassNotFoundException e) { e.printStackTrace(); } catch (IllegalArgumentException e) { e.printStackTrace(); } catch (SecurityException e) { e.printStackTrace(); } catch (InstantiationException e) { e.printStackTrace(); } catch (IllegalAccessException e) { e.printStackTrace(); } catch (InvocationTargetException e) { e.printStackTrace(); } [ 26 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
In the given sample code, you can see that there is a new class called the Assembler. The Assembler, in its main method, invokes the implementation class of TaxCalculator that we want RentCalculator to use. The Assembler then instantiates an instance of RentCalculator, injects the TaxCalculator instance of the type we specify into it, and calls the calculateRent method. Thus the two classes are not tightly coupled and the program control lies with the assembler, unlike in the previous case. Thus there is Inversion of Control happening here, as the framework (Assembler in this case) is controlling the execution of the program. This is a very trivial sample. We can write an assembler class that is more generic and is not even coupled to the interface as in the previous case. This is an example of dependency injection. An injection of this type is called constructor injection, where the assembler injects values through the constructor. You can also have other types of dependency injection, namely setter injection and field injection. In the former, the values are injected into the object by invoking the setter methods that are provided by the class, and in the latter, the values are injected into fields through reflection or some other method. The Apache Geronimo kernel uses both setter injection and constructor injection for resolving dependencies between the different modules or configurations that are deployed in it. The code for these examples is provided under di-sample in the samples. To build the sample, use the following command: mvn clean install [ 27 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture
To run the sample without dependency injection, use the following command: java –cp di-sample-1.0.jar packtsamples.Main
To run the sample with dependency injection, use the following command: java –cp di-sample-1.0.jar packtsamples.Assembler packtsamples. di.ServiceTaxCalculator
GBeans
A GBean is the basic unit in Apache Geronimo. It is a wrapper that is used to wrap or implement different services that are deployed in the kernel. GBeans are similar to MBeans from JMX. A GBean has attributes that store its state and references to other GBeans, and can also register dependencies on other GBeans. GBeans also have lifecycle callback methods and metadata. The Geronimo architects decided to invent the concept of GBeans instead of using MBeans in order to keep the Geronimo architecture independent from JMX. This ensured that they did not need to push in all of the functionality required for the IoC container (that forms Geronimo kernel) into the JMX implementation. Even though GBeans are built on top of MBeans, they can be moved to some other framework as well. A user who is writing a GBean has to follow certain conventions. A sample GBean is shown below: import org.apache.geronimo.gbean.GBeanInfo; import org.apache.geronimo.gbean.GBeanInfoBuilder; import org.apache.geronimo.gbean.GBeanLifecycle; public class TestGBean implements GBeanLifecycle{ private String name; public TestGBean(String name){ this.name = name; } public void doFail() { System.out.println("Failed............."); } public void doStart() throws Exception { System.out.println("Started............"+name); } public void doStop() throws Exception { System.out.println("Stopped............"+name); } public static final GBeanInfo GBEAN_INFO; static { GBeanInfoBuilder infoBuilder = GBeanInfoBuilder .createStatic(TestGBean .class, "TestGBean"); [ 28 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
You will notice certain characteristics that this GBean has from the previous section. We will list these characteristics as follows: •
All GBeans should have a static getGBeanInfo method, which returns a GBeanInfo object that describes the attributes and references of GBean as
well as the interfaces it can implement. •
All GBeans will have a static block where a GBeanInfoBuilder object is created and linked to that GBean. All of the metadata that is associated with this GBean is then added to the GBeanInfoBuilder object. The metadata includes descriptions of the attributes, references, interfaces, and constructors of GBean.
We can add GBeans to configurations either programmatically, using methods exposed through the configuration manager and kernel, or by making an entry in the plan for the GBean, as follows:
Nitya
We need to specify the attribute values in the plan, and the kernel will inject those values into the GBean at runtime. There are three attributes for which we need not specify values. These are called the magic attributes, and the kernel will automatically inject these values when the GBeans are being started. These attributes are abstractName, kernel, and classLoader. As there is no way to specify the values of these attributes in the deployment plan (an XML file in which we provide Geronimo specific information while deploying a configuration), we need not specify them there. However, we should declare these attributes in the GBeanInfo and in the constructor. If the abstractName attribute is declared, then the Geronimo kernel will inject the abstractName of the GBean into it. If it is the kernel attribute, then a reference to the kernel that loaded this GBean is injected. If we declare classLoader, then the class loader for that configuration is injected. More on how to do this will be discussed in Chapter 14, Geronimo Internals.
[ 29 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture
Configurations
A group of GBeans that provide a certain service is called a configuration. A configuration has a name, can declare dependencies on other configurations, and is the basic deployable unit in Apache Geronimo. The GBeans that you write can only be deployed in Geronimo as part of a configuration. When you deploy a new service or an enterprise application in Apache Geronimo, the configuration details that you provide by means of a deployment plan are parsed and a configuration is created. Internally, a configuration is another GBean that actually groups a number of GBeans within it. A configuration contains the following persistable attributes: •
•
•
Its configurationData The configurationData represents all of the information that is stored in this configuration. Among the information that it contains is the classpath of this configuration (a list of URLs to locations where the classes representing this configuration are located), its configurationId (a unique ID for identifying this configuration to the kernel), the namespace of this configuration, and a byte array representing the state of all of the GBeans in this configuration. The list of its parents This is the list of parent configurations for this configuration. A configuration can have multiple parents, and each parent can in turn have multiple parents, and so on. A reference to a ManageableAttributeStore A manageable GBean attribute is one that can be changed at runtime by an administrator in order to change the behavior of the service that is wrapped by the GBean. For example, if we have a simple HttpServer service that is managed by a GBean, then one possible manageable attribute is the port on which the server will be listening. The ManageableAttributeStore is a repository where the manageable attributes are stored so that they are more easily accessible to the end user when compared to serialized configurations. Changes to the manageable attributes of the GBeans are made to the store and is persisted in the config.xml file present in the / var/config directory. There is also a config-substitutions.properties file for values of variables in the config.xml file. Each configuration is given a unique name. The name of a configuration as it is specified in the deployment plan of that module is, as follows:
org.apache.geronimo.configs openejb 2.1.4 car
[ 30 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 2
The name of the configuration is in the format // / •
groupId: The groupId identifies a group of related modules. If no group ID is specified for a module or an application, then its groupId is taken as default. If
no group ID is specified for a dependency entry, then it is taken as a wildcard and instances of groupId are not used in the search. •
artifactId: The artifactId identifies the artifact within the group. It should be unique within the group. If the artifactId is not specified, then it will be defaulted to the name of the module file.
•
version: The version is the version of that artifact. It can take the form 1.x.x. If it is not specified, then the version is taken as the timestamp at the time of deploying the configuration
•
type: This represents the type of the artifact. It can be car for system services and jar, ear, war, and so on for other modules.
Dependencies
A module or configuration can have dependencies on other modules. You can specify the dependencies on other modules through the dependency tag, as shown below:
org.apache.geronimo.configs j2ee-server 2.1.4 car
org.apache.geronimo.framework geronimo-kernel 2.1.4 jar
[ 31 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture
Most commonly, users will need to give dependencies on other configurations, services, or libraries. There is a difference in the way in which these dependencies are handled by the Geronimo kernel. In the case of a dependency on a configuration, all of the services of that configuration as well as the classes, are available to the current configuration. A configuration, specified as a dependency becomes a parent of the current configuration. Its class loader becomes the parent of the current configuration's class loader. If the dependency is on a jar type artifact, which is not a configuration, the classes of that jar type artifact are added to the classpath of the current configuration.
High-level architecture
Apache Geronimo consists of a lightweight kernel that provides services such as Lifecycle Management, Dependency Management, Repository, and Configuration Management to the other services that are deployed on it. As we saw earlier in the chapter, the basic manageable unit in Apache Geronimo is the GBean. GBean is a manageable wrapper object with attributes, references, and lifecycle callback methods. It also has a static GBEAN_INFO attribute, which is, a description used by the kernel to instantiate, manage, and modify the GBean state. The following diagram shows the Apache Geronimo kernel and all of the services that it provides, as well as the other services that are layered on top of the basic kernel services: Java EE Container System
Security
Work Management
Deployments Dependency Management
Lifecycle Management
Kernel Repository
Configuration Management Naming
Transactions
Remoting
[ 32 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 2
This architecture is the key for Geronimo's extensibility. It adds new services or plugins as services deployed on the server, which are in the form of GBeans whose state, dependencies, and lifecycle are managed by the kernel. A GBean may have a reference to another GBean, and the kernel makes sure that the GBean has access to a properly initialized and started instance of that GBean. The Configuration Manager is a component in the Apache Geronimo kernel that takes care of starting the configurations in the requisite order and also of providing the plumbing required to connect related and dependent configurations together so that they can consume the services of other configurations. The Apache Geronimo kernel also provides the Repository and configuration store that contains configurations of the existing modules as well as the required libraries. Any new module that you add will also be added to the Repository. If it is a configuration archive, then it will be added to the configuration store as well. By the Geronimo kernel, we mean the core of Geronimo that provides the services shown in the previous diagram. We will also be referring to the org.apache.geronimo.kernel.Kernel interface. This is the core interface whose implementations will actually manage GBeans. Whenever we refer to the Kernel implementation, we mean implementations of this interface. We will be referring to both of these, and you should keep in mind the subtle difference between them.
We will now see each of the services that the kernel provides, in detail: •
Repository The repository is the place where Apache Geronimo stores the majority of the artifacts that it contains. The repository consists of two types of artifacts: °
Libraries: The libraries are utilized by Apache Geronimo as well as the applications that are deployed on it. The libraries are usually JAR files that contain a number of classes. The libraries may be standalone or be included in a configuration. An example of a commonly-used library is log4j for logging. The log4j library will be present in the repository in the directory /repository/log4j/log4j/1.2.14/log4j1.2.14.jar.
[ 33 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture
°
Configurations: These are the configurations that are deployed in Apache Geronimo. A configuration represents a set of services that can be loaded and brought online by the Geronimo kernel. Once you deploy a module, the configuration information is serialized to the disk in a subdirectory of /repository, along with the libraries that provide the functionality of that module. The serialized configuration information generally consists of the information in the deployment plan as well as the values for different GBean attributes, and queries for different GBean references. It is stored in the META-INF directory directly inside the root directory of the configuration. The path of the root directory of the configuration will consist of the group ID of the configuration, with dots replaced by slashes. A configuration will always have a directory name ending with .car. For example, the openEJB configuration will be present in the repository in the /repository/org/apache/ geronimo/configs/openejb/2.1.4/openejb-2.1.4.car
•
•
directory as its artifactId is org.apache.geronimo. configs/openejb/2.1.4/car. Configuration Management The kernel manages all of these tasks, from creating new configurations to linking them to their parents and children, serializing them to disk, reading them back, as well as managing the attributes of the GBeans. There is a configuration manager GBean which manages these tasks. An additional task that the kernel performs is to make MBean wrappers for the GBeans so that they can be managed remotely over JMX. Lifecycle Management This is another service that is provided by the kernel. This actually includes providing lifecycle management to all of the services that are deployed in Apache Geronimo. The Kernel implementation provides Lifecycle Management through GBeans. The Kernel implementation is actually aware of GBeans only, and it can Start, Stop, Load, and Unload GBeans. GBeans that implement the org.apache.geronimo.gbean.GBeanLifecycle interface will provide implementations of callback methods that will be called by the Kernel after starting (doStart), before stopping (doStop), and in case of failure (doFail). The kernel internally has a LifecycleMonitor that will be sent notifications whenever a GBean is loaded, starting, running, stopping, stopped, failed, or unloaded. The notifications are sent by a LifecycleBroadcaster. The LifecycleMonitor will have a number of instances of LifecycleListener that are registered with it, and they are configured to perform tasks corresponding to the state notifications that they receive. [ 34 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 2
•
Dependency Management Finally, the Apache Geronimo Kernel provides Dependency Management— that is, the management of dependencies for the services deployed in the server. The dependencies for a configuration or module are specified in the deployment plan for that module. So the kernel provides the plumbing that will link a configuration together with all of its dependencies. Dependency Management also includes making sure that all of the services that a configuration depends on are started before the configuration is started. Again at the Kernel implementation level the dependencies are between GBeans, and the Kernel manages starting all of the dependencies of a GBean before it is started, as well as making them available to the GBean at runtime.
Class loader architecture
This section covers the class loader architecture for Apache Geronimo. The following image shows the class loader hierarchy for an application that is deployed in Apache Geronimo: BootStrap Extensions System org.apache.geronimo.framework/j2ee-system//car SystemDatabase
EAR WAR
The BootStrap class loader of the JVM is followed by the Extensions class loader and then the System class loader. The j2ee-system class loader is the primary class loader of Apache Geronimo. After the j2ee-system class loader, there are multiple other layers of class loaders before reaching the application class loaders. Applications have an application class loader, which loads any required application-level libraries and EJB modules. However, the web application packaged in the EAR will have its own class loader. The Administration Console has a ClassLoader Viewer portlet that can be used to view the class loader hierarchy as well as the classes loaded by each class loader.
[ 35 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture
Modifying default class loading behavior
In certain situations, we will need to follow a class loading strategy that is different from the default one that is provided by Apache Geronimo. A common situation where we need this functionality is when a parent configuration uses a library that is also used by the child and the library used by the parent is a different version, which is incompatible with the child's version of the library. In this case, if we follow the default class loading behavior, then we will always get the classes loaded by the parent configuration and will never be able to reference the classes in the library present in the child configuration. Apache Geronimo provides you with the ability to modify the default class loading behavior at the configuration level to handle such scenarios. This is done by providing certain elements in the deployment plan which, if present, will change the class loading behavior. These elements and the changes in class loading behavior that they represent, are explained as follows: •
hidden-classes: This tag is used to hide classes that are loaded in parent
class loaders, so that the child class loader loads its own copy. Similarly, we can use this tag to specify the resources that should be loaded from the configuration class loader. For example, consider the case where you have a module that needs to load its copy of log4j. The server also has its own copy used for logging that is loaded in the parent class loader. We can add the hidden-classes element in the deployment plan for that module so that it loads its own copy of log4j, and the server loaded version of log4j is hidden from it.
•
non-overridable-classes: This element specifies the list of classes that can be loaded only from the parent configurations of this configuration. In other words, the classes specified in this element cannot be loaded by the current configuration's class loader. The non-overridable-classes element is for preventing applications from loading their own copies of classes that should always be loaded from the parent class loaders, such as the Java EE API classes.
•
private-classes: The classes that are defined by this tag will not be visible to class loaders that are the children of the current class loader. These classes will be loaded either from the current class loader or from its parents. The same class loading behavior can be achieved by using the hidden-classes tag in all of the child class loaders.
[ 36 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 2
•
inverse-classloading: If this element is specified, then the standard class loading strategy will be reversed for this module. This in effect means that a class is first looked up from the current class loader and then from its parent. Thus, the class loader hierarchy is inverted.
•
suppress-default-environment: This will suppress the environment
that is created by the builder for this module or configuration. This is a rarely-used element and can have nasty side effects if it is used carelessly.
Important modules
In this section, we will list the important configurations in Apache Geronimo. We will group them according to the Apache or other open source projects that they wrap. Configurations that do not wrap any other open source project will be listed under the Geronimo section. Apache ActiveMQ org.apache.geronimo.configs/activemq-broker/2.1.4/car org.apache.geronimo.configs/axis/2.1.4/car Apache Axis org.apache.geronimo.configs/axis-deployer/2.1.4/car Apache Axis2
org.apache.geronimo.configs/axis2-ejb-deployer/2.1.4/ car org.apache.geronimo.configs/cxf/2.1.4/car org.apache.geronimo.configs/cxf-deployer/2.1.4/car org.apache.geronimo.configs/cxf-ejb/2.1.4/car
Apache Derby
org.apache.geronimo.configs/cxf-ejb-deployer/2.1.4/ car org.apache.geronimo.configs/derby/2.1.4/car
Apache Geronimo org.apache.geronimo.configs/client/2.1.4/car org.apache.geronimo.configs/client-deployer/2.1.4/car org.apache.geronimo.configs/client-security/2.1.4/car org.apache.geronimo.configs/client-transaction/2.1.4/ car org.apache.geronimo.configs/clustering/2.1.4/car org.apache.geronimo.configs/connector-deployer/2.1.4/ car
[ 37 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture
org.apache.geronimo.configs/farming/2.1.4/car org.apache.geronimo.configs/hot-deployer/2.1.4/car org.apache.geronimo.configs/j2ee-deployer/2.1.4/car org.apache.geronimo.configs/j2ee-server/2.1.4/car org.apache.geronimo.configs/javamail/2.1.4/car org.apache.geronimo.configs/persistence-jpa10deployer/2.1.4/car org.apache.geronimo.configs/sharedlib/2.1.4/car org.apache.geronimo.configs/transaction/2.1.4/car org.apache.geronimo.configs/webservices-common/2.1.4/ car org.apache.geronimo.framework/client-system/2.1.4/car org.apache.geronimo.framework/geronimo-gbeandeployer/2.1.4/car org.apache.geronimo.framework/j2ee-security/2.1.4/car org.apache.geronimo.framework/j2ee-system/2.1.4/car org.apache.geronimo.framework/jee-specs/2.1.4/car org.apache.geronimo.framework/jmx-security/2.1.4/car org.apache.geronimo.framework/jsr88-cli/2.1.4/car org.apache.geronimo.framework/jsr88deploymentfactory/2.1.4/car org.apache.geronimo.framework/offline-deployer/2.1.4/ car org.apache.geronimo.framework/online-deployer/2.1.4/ car org.apache.geronimo.framework/plugin/2.1.4/car org.apache.geronimo.framework/rmi-naming/2.1.4/car org.apache.geronimo.framework/server-securityconfig/2.1.4/car org.apache.geronimo.framework/shutdown/2.1.4/car org.apache.geronimo.framework/transformeragent/2.1.4/car org.apache.geronimo.framework/upgrade-cli/2.1.4/car Apache Yoko
org.apache.geronimo.configs/j2ee-corba-yoko/2.1.4/car org.apache.geronimo.configs/client-corba-yoko/2.1.4/ car
[ 38 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
org.apache.geronimo.configs/jaxws-ejb-deployer/2.1.4/ car org.apache.geronimo.configs/jsr88-earconfigurer/2.1.4/car org.apache.geronimo.configs/jsr88-jarconfigurer/2.1.4/car org.apache.geronimo.configs/jsr88-rarconfigurer/2.1.4/car org.apache.geronimo.configs/jsr88-warconfigurer/2.1.4/car org.apache.geronimo.configs/myfaces/2.1.4/car
Apache OpenEJB
org.apache.geronimo.configs/myfaces-deployer/2.1.4/ car org.apache.geronimo.configs/openejb/2.1.4/car
Apache OpenJPA
org.apache.geronimo.configs/openejb-corbadeployer/2.1.4/car org.apache.geronimo.configs/openejb-deployer/2.1.4/ car org.apache.geronimo.configs/openjpa/2.1.4/car
Spring
org.apache.geronimo.configs/spring/2.1.4/car
Apache Tomcat6
org.apache.geronimo.configs/tomcat6/2.1.4/car
JSR 88
org.apache.geronimo.configs/tomcat6-clusteringbuilder-wadi/2.1.4/car org.apache.geronimo.configs/tomcat6-clusteringwadi/2.1.4/car org.apache.geronimo.configs/tomcat6-deployer/2.1.4/ car org.apache.geronimo.configs/tomcat6-no-ha/2.1.4/car Apache WADI
org.apache.geronimo.framework/gshell-framework/2.1.4/ car org.apache.geronimo.framework/gshell-geronimo/2.1.4/ car org.apache.geronimo.framework/xmlbeans/2.1.4/car
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture
If you check the configurations, then you will see that most of the components that make up Geronimo have a deployer configuration and a main configuration. The deployer configuration contains the GBeans that will deploy modules onto that component. For example, the openejb-deployer contains GBeans that implement the functionality to deploy an EJB module onto Apache Geronimo. For accomplishing this, the EJB JAR file and its corresponding deployment plan are parsed by the deployer and then converted into a format that can be understood by the OpenEJB subsystem. This is then deployed on the OpenEJB container. The main configuration will usually contain the GBeans that configure the container and also manage its lifecycle.
Server directory structure
It is important for a user or an administrator to understand the directory structure of a Geronimo server installation. The directory structure of a v2.1.4 server is shown in the following screenshot:
Please note that the directory that we will be referring to as is the geronimo-tomcat6-javaee5-2.1.4 directory shown in the screenshot.
[ 40 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 2
The following are some important directories that you should be familiar with: • • • • •
• • • •
The bin directory contains the command scripts and the JAR files required to start the server, stop the server, invoke the deployer, and start the GShell. The etc directory contains the configuration files for GShell. The lib directory contains the JAR files required to start the basic Geronimo framework. The schema directory contains Geronimo schemas. The var/config directory contains Geronimo configurations files. A Geronimo administrator or user can find most of the configuration information about the server here. The var/derby directory contains the database files for the embedded Derby database server. The var/log directory contains logging configuration and logfiles. The var/security directory contains user credential and grouping files. The var/security/keystores directory contains the cryptographic keystore files used for server SSL configuration.
The following are some important configuration files under the Geronimo directory structure: •
config.xml: This file is located under the /var/config
•
config-substitutions.properties: This file is located under the /var/config directory. The property values specified in this file are used in expressions in config.xml. The property values in
directory. This file preserves the information regarding GBean attributes and references that were overridden from the default values used at deployment time.
this file can be overridden by using a system property or environment variable with a property name that is prefixed with org.apache.geronimo. config.substitution.
•
artifact_aliases.properties: This file is located under the /var/config directory. This file is used to substitute
one module or configuration ID for another module or configuration ID. The entries in this file are of the form oldArtifactId=newArtifactId, for example default/mylib//jar=default/mylib/2.0/jar. Note that the version number in the old artifact ID may be omitted, but the version number in the new artifact ID must be specified. •
client_artifact_aliases.properties: This file is located under the /var/config directory. This file is used for artifact
aliasing with application clients.
[ 41 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture
•
•
•
•
•
server-log4j.properties: This file is located under the / var/log directory. This file contains the logging configuration for the server.
More details about this configuration can be found in Chapter 13, Logging. deployer-log4j.properties: This file is located under the /var/log directory. This file contains the logging configuration for the deployer. More details about this configuration can be found in Chapter 13, Logging. client-log4j.properties: This file is located under the /var/log directory. This file contains the logging configuration for application clients. More details about this configuration can be found in Chapter 13, Logging. users.properties: This file is located under the /var/ security directory. This file contains the authentication credentials for the server. See Chapter 6, Security, for more details. groups.properties: This file is located under the /var/ security directory. This file contains the grouping information for the users defined in users.properties. See Chapter 6, Security, for more details.
Among the directories that contain sensitive information, such as user passwords, are var/security, var/derby, and var/config. These directories should be protected using operating system provided directory and file security.
Deployment architecture
In this section, we discuss some of the important aspects of deployment of artifacts on a Geronimo server.
Deployer
The deployer aggregates all instances of the ConfigurationBuilder available on the server and invokes the appropriate ConfigurationBuilder to deploy an archive, or a Geronimo-specific deployment plan XML file, or both. The deployer can be used through the web-based Administration Console, command-line deploy tool, hot-deployer, or GShell. Note that Administration Console, command line deploy tool, and GShell provide the option to specify an archive and a plan, whereas hot-deployer requires that the plan be packaged inside the archive. Installed modules, applications, and services configurations can be uninstalled using the command-line deploy tool or GShell, and specifying the configuration ID. Configurations can also be uninstalled by clicking on the uninstall link in the Administration Console from the appropriate Applications portlets page. See Chapter 10, Administration, for more details on portlets in the Administration Console. [ 42 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 2
Repository
Geronimo uses the Maven 2 type artifact repositories for library files, resources, and deployed configurations. The root of this repository is the directory /repository. This repository contains all of the server runtime configurations. An artifact with ID /// is located under the directory /repository// / with the filename -.. For example, the log4j JAR file that has an artifact ID of log4j/log4j/1.2.14/jar is located in the /repository/log4j/log4j/1.2.14 directory under the filename log4j-1.2.14.jar. When the groupId contains a dot (period), it results in a subdirectory rather than a directory with a dot in the directory name. For example, the RAR file corresponding to org.tranql/tranql-connector-ra/1.4/rar is located under the /repository/org/tranql/tranql-connectorra/1.4 directory rather than /repository/org.tranql/tranqlconnector-ra/1.4.
Configuration builder
A configuration builder creates a runtime configuration containing a class loader definition and GBeans that represent the function to be provided by deploying an application archive or a service plan in Geronimo. The archive or plan is translated into a set of GBeans. The definition of the GBeans is already available on the server or provided in the archive that is being deployed. The configuration builders deployed in the server are aggregated by the Deployer to provide a single interface for deploying all kinds of supported archives and/or plans. EARConfigBuilder and ServiceConfigBuilder are two configuration builders that are included in a Geronimo server by default. A configuration builder implements the org.apache.geronimo.deployment. ConfigurationBuilder interface shown in the following listing: public interface ConfigurationBuilder { static final String CONFIG_BUILDER = "ConfigBuilder"; Object getDeploymentPlan(File planFile, JarFile module, ModuleIDBuilder idBuilder) throws DeploymentException; Artifact getConfigurationID(Object plan, JarFile module, ModuleIDBuilder idBuilder) throws IOException, DeploymentException; DeploymentContext buildConfiguration( boolean inPlaceDeployment, //Boolean specifying whether to deploy in place Artifact configId,// the configuration id Object plan, // the deployment plan JarFile module, // the archive to deploy [ 43 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture Collection configurationStores, // the list of config stores ArtifactResolver artifactResolver, ConfigurationStore targetConfigurationStore // target store ) throws IOException, DeploymentException; }
During the deployment, the getDeploymentPlan() method of each ConfigurationBuilder is invoked with the archive and/or plan files received for deployment. The configuration builder examines the provided archive and plan files, and returns the plan if that configuration builder can handle the deployment. The first configuration builder to return a non-null plan is chosen as the candidate to deploy the archive and/or plan. The candidate configuration builder's getConfigurationID() method determines the ID of the configuration under which the deployment will happen. Note that any fields in the configuration ID that are not determined by the configuration builder will be set to the default values by the deployer. The configuration ID will determine the directory under the repository into which the configuration will be deployed. The configuration builder's buildConfiguration() performs the moving of unpacked configuration directories to the repository and creates the necessary GBeans to complete the deployment. Configuration builders use instances of ModuleBuilder and NamingBuilder to handle the individual modules in the deployment process. Any new ConfigurationBuilder GBeans that are started in the server at runtime get dynamically added to the deployer and are immediately available for use.
Module builder
Geronimo's EARConfigBuilder uses instances of ModuleBuilder to process individual web, EJB, connector, and application client modules in the deployment process. A ModuleBuilder processes the configuration and creates GBeans corresponding to a module that ModuleBuilder is capable of processing. Some instances of the ModuleBuilder that are available in Geronimo are given as follows: •
EjbModuleBuilder
•
TomcatModuleBuilder
•
JettyModuleBuilder
•
ConnectorModuleBuilder
•
AppClientModuleBuilder
A ModuleBuilder GBean implements the interface org.apache.geronimo.j2ee. deployment.ModuleBuilder. The interface definition is as follows: public interface ModuleBuilder { Module createModule(File plan, JarFile moduleFile, Naming naming, ModuleIDBuilder idBuilder) [ 44 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
The createModule() method processes the individual Java EE module—that is, either a part of an EAR or being deployed as a standalone module, creates the artifacts that need to be installed, and also creates additional dependencies that need to be added to the configuration. The installModule() method handles the copying of artifacts to the repository. The initContext() method handles the initialization of the application context. The addGBeans() method handles the adding of any GBeans to the module's configuration.
Module builder extension
A ModuleBuilderExtension to a ModuleBuilder provides additional processing on the module over and above those provided by the ModuleBuilder. A ModuleBuilderExtension implements the interface org.apache.geronimo.j2ee. deployment.ModuleBuilderExtension. This interface definition is given in the following listing: public interface ModuleBuilderExtension { void createModule(Module module, Object plan, JarFile moduleFile, String targetPath, URL specDDUrl, Environment environment, Object moduleContextInfo, AbstractName earName, Naming naming, ModuleIDBuilder idBuilder) throws DeploymentException; [ 45 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Each ModuleBuilder can be configured with zero or more instances of ModuleBuilderExtension. During each of the method invocations in ModuleBuilder, once the processing by the ModuleBuilder is completed, the method invokes the corresponding method on each of the configured instances of ModuleBuilderExtension so that the extension completes additional processing. For example, MyFacesModuleBuilderExtension for TomcatModuleBuilder takes care of processing MyFaces configuration files and adding necessary additional dependencies and GBeans to the configuration.
Naming builder
Instances of ModuleBuilder and ModuleBuilderExtension use instances of NamingBuilder to process the Geronimo naming of related XML elements, for example, EJB references, GBean references, and so on, in the deployment plans. Some instances of the NamingBuilder are: •
EjbRefBuilder
•
ResourceRefBuilder
•
CorbaRefBuilder
•
TSSLinkBuilder
•
EnvironmentEntryBuilder
•
GBeanRefBuilder
The instances of NamingBuilder to be used by instances of ModuleBuilder and ModuleBuilderExtension are configured in a NamingBuilderCollectionGBean.
Hot deployment
Geronimo provides hot deployment by means of DirectoryHotDeployer, whereby the files copied to the /deploy directory are automatically deployed to the Geronimo server. [ 46 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 2
Deployment watcher
A DeploymentWatcher enables the receipt of notifications about configurations being deployed to and removed from the server. A DeploymentWatcher implements the interface org.apache.geronimo.kernel.DeploymentWatcher. The interface definition is given in the following listing: public interface DeploymentWatcher { void deployed(Artifact id); void undeployed(Artifact id); }
For example, the DirectoryHotDeployer, which is a DeploymentWatcher, handles the removal of files from the hot-deploy directory when the configuration being removed is originally deployed using the hot deployer.
Plugins
A Geronimo plugin is a predeployed configuration that contains a class loader description, GBeans, and other resources. An example is the Quartz plugin that, upon installation, provides sophisticated scheduling functionality to applications being deployed on Apache Geronimo. A plugin defines prerequisite configurations as well as dependencies that must be downloaded. As it is already processed by the deployer, a plugin JAR is directly extracted into the server's repository without going through a deployment step where the configuration is created. A plugin installation differs from a normal deployment in the way that any non-prerequisite dependencies for the plugin will be downloaded during installation. The prerequisite configurations must have already been deployed in the server for the plugin to be installed. Note that in case of a regular deployment, all of the dependencies must already exist in the repository. Plugins can be installed by using the command-line deploy tool, the Administration Console, or the GShell.
Plugin catalog and plugin repository
A Plugin archive file contains a metadata file geronimo-plugin.xml under the META-INF directory. This geronimo-plugin.xml file contains descriptive information about the plugin, such as the plugin category, URL for a site that contains more information on the plugin, content to be added to config.xml for customization of GBeans, property values to be added to config-substitutions.properties, artifact aliases to be added to artifact-aliases.properties, a description of the content to be unpacked to the server directory, and so on. The information from multiple plugins is collected into a plugin catalog called geronimo-plugins.xml. A maven repository containing plugins and a plugin catalog is referred to as a plugin repository. [ 47 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Architecture
Custom server assemblies
Starting from v2.1, a Geronimo server is completely assembled out of plugins. This architecture provides the ability to assemble a server containing only selected configurations according to a user's interest, and the necessary dependencies. This provides the users with the ability to start with a full Java EE server, deploy the user's applications, and then extract a server with the minimum footprint required to run the user's applications. Assembling a server in this manner can be done using the Plugins portlet in the Administration Console or by using the assemble-server GShell command. Note that the org.apache.geronimo.assemblies/geronimoboilerplate-minimal/2.1.4/jar configuration must be included in order to have a working server. Another way to create a custom server assembly is to use the car-maven plugin and build the server using Maven to include geronimoboilerplate-minimal, along with your plugin(s) that need to be part of the server. See Chapter 9, Geronimo Plugins, for more details on creating custom server assemblies.
Extensible Administration Console
The flexible server assemblies require that the Administration Console is also flexible, in order to provide the administration functionality for the newly added components as plugins to be made available from a single place. New functions can be added to the Administration Console by installing Administration Console Extensions. This provides the plugin developers with the capability to package administration components along with the functional components of their plugin. See Chapter 9, Geronimo Plugins, for details on creating Administration Console Extensions.
Summary
We conclude this chapter after having gone through a fairly detailed overview of the architecture of Apache Geronimo, as well as the base pattern behind the Geronimo kernel—that is, dependency injection. We have covered GBeans, configurations, dependencies, and the repository. We then had a look at the high-level architecture of Apache Geronimo. We covered the functionality that the Apache Geronimo kernel exposes and had a look at the class loader hierarchy in Apache Geronimo. We listed the important system-level modules and explained the difference between normal and deployer modules. Finally, we discussed the deployment architecture and plugins. This brings us to the end of the chapter on the Apache Geronimo architecture. The authors hope that you now have a fairly detailed understanding of the Kernel and that you will be able to understand the Apache Geronimo source code better with this in mind. In the next chapter, you will learn about configuring database connectivity and using the Apache Derby database embedded in Apache Geronimo. [ 48 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity Apache Geronimo is used for hosting Java EE enterprise applications. All enterprise applications operate on data and in most of them, all or a part of this data is stored in a relational database. Therefore, it is important for an application server to provide an infrastructure for applications to simplify and optimize relational database access. Java applications use the Java Database Connectivity (JDBC) API for SQL-based database access. This is an API that is independent of the underlying database. The database vendors provide JDBC drivers for their respective RDBMSes. The Java EE application server provides a mechanism for optimizing and simplifying database access through connection pools. The server creates a pool of connections so that the applications can reuse the connections in the pool. As a result, the applications are spared from creating and closing connections, and the connection reuse actually speeds up the process as it is more efficient than creating connections whenever required. Another advantage is that it ensures that the application code will not contain any RDBMS vendor-specific code, thereby making it possible to swap the RDBMS used without changing any code. Apache Geronimo provides these features with the help of the TranQL framework. The TranQL framework wraps JDBC drivers in J2CA connectors, and so in Apache Geronimo, JDBC connectivity is also exposed through J2CA just like it is for JMS. This enables both database and JMS invocations to be part of a single transaction. Geronimo supports JDBC connection pools with local transaction support, and also ones with XA transaction support. All you have to do is configure the resource adapter with the JDBC properties that you would use to establish a JDBC connection directly, and the resource adapter will create the database pool. Creating a database connection upon each request is costly in terms of resource usage, and it holds on to resources unnecessarily. With a database pool, the created connections are placed in a pool and reused so that new connections need not be made unless the connections in the pool are all in use. This also reduces the waiting time of the application to obtain a connection to the database.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity
There are generic TranQL connectors in Geronimo that can support any relational database and there are also database-specific resource adapters. All of the XA connectors are database-specific and so XA support is provided only for a limited number of databases. The TranQL RAR files contain the connection pooling logic that is used by Geronimo. In this chapter, you will learn: •
The scope of database pools
•
Creating a server-wide database pool
•
Creating an application-scoped database pool
•
Creating a client-scoped database pool
•
Editing an existing database pool
•
Importing a database pool from another application server
•
Using a database pool in an application
Database pool scopes
In Apache Geronimo, you can deploy database pools with three different scopes. The different scopes and their significance are explained as follows: •
Server-wide: If your database pool is server-wide, it will be visible throughout the entire server instance. Any application or service that is deployed on the server can then look up and use the connections in that pool. You can also use the @Resource annotation in your application code to get the database pool injected instead of using lookups.
•
Application-scoped: An application-scoped database pool is visible only inside an enterprise application. It is not visible to other enterprise applications or services that are deployed on the same application server that are separate from this enterprise application. All of the different Java EE modules that are packaged inside the enterprise application in whose scope the pool is created will have access to that pool. So if an EAR file has both web and EJB modules, then they will be able to access and use a database pool declared in the EAR file's scope. Note that an application-scoped database pool can still be accessed by another application if it declares a dependency on the application that declares the pool.
•
Client-scoped: A client-scoped database pool is visible only in the scope of the application client which declares it. This scope is used when application clients want to access relational databases. Application clients run inside a client container—that is, separate from the application server—and so they cannot access database pools that are declared on the server side. [ 50 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 3
Application-scoped database pools can only be deployed with EAR applications. The advantage of using application-scoped database pools is that you can deploy and manage your application and your database pool as a single deployment unit. Standalone web and EJB applications can use server-wide database pools. The advantage of using server-wide database pools is that you can redeploy just the database pool without affecting the deployed applications that use the database pool. You can choose to deploy your database pool as a Server-wide pool or as an Application-scoped pool depending on your requirement.
Creating a server-wide database pool
In order to set up connectivity with any RDBMS from Apache Geronimo, you first need to obtain the JDBC drivers for that particular RDBMS. These drivers can be obtained from the database vendor or from a third party having a license to provide JDBC drivers for that RDBMS. Once you obtain the JDBC driver, you need to install it into Apache Geronimo's server repository. You can then set up a database pool using the TranQL resource adapters and the JDBC drivers. There are four ways in which you can set up a server-wide database pool, as we will see now.
Using the Administration Console Wizard
The steps for downloading and installing JDBC drivers and setting up a database pool using the Administration Console Wizard are given in the next example. We will create a database pool with the name TestDBPool for the HSQLDB embedded database. 1. Start the Apache Geronimo server instance and bring up the Administration Console in your favorite web browser, by using the URL http://localhost:8080/console. 2. Log in with the username system and password manager. 3. On the left-hand side of the Console Navigation pane under Services, click on the Database Pools link, as shown in the following screenshot:
[ 51 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity
4. This will bring up the Database Pools portlet, as shown in the next screenshot. The Database Pools portlet shows the list of pools that are already deployed on this Geronimo server instance. It provides three links to create a database pool in three ways, namely, by using the database pool wizard, by importing the database pool from JBoss 4, or by importing the database pool from Weblogic 8.1.
5. Click on Using the Geronimo database pool wizard. This brings up the first screen of a sequence of screens that will guide you through the process of creating a database pool. This is shown in the following screenshot:
[ 52 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 3
6. Enter the Name of Database Pool that you want to create, select the Database Type from the drop-down list, and then click on Next. For our example, enter the name TestDBPool and select HLSQLDB embedded as the Database Type. Click on Next to bring up the next screen, as shown in the following screenshot:
7. In this screen you need to enter values for the following fields: •
Driver JAR: The JAR file(s) that contain the database driver
•
DB User Name: The username used to connect to the database
•
DB Password: The password that is required to connect to the database
•
Confirm Password: The same as the DB Password, entered once more for confirmation
•
Database: The name of the database
8. We can see that the Driver JAR select box is empty, which means that the HSQLDB embedded driver is not present in the server repository. We can download and install this driver from the Administration Console. To do this, click on the Download a Driver button. If the select box is not empty, then you can select the corresponding driver if it is available. [ 53 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity
9. This brings us to the next screen, where we can select the driver that we want from the Select Driver drop-down list, and then click on Next. For our example, select HSQLDB 1.7.3, and then click on Next. This will bring up the next screen with a progress bar that shows the download progress of the driver, as shown in the next screenshot:
See the topic Installing unlisted drivers, for steps to manually download and install JAR files in the repository. 10. Once the download completes, the Driver JAR drop-down list in Step 2, Select Driver, JAR, Parameters, is filled with the name of the JAR driver that has been downloaded and installed in the Geronimo repository. 11. Enter values for the other fields, and then click on Next. The values we are entering are DB User Name: system, DB Password: manager, and Database: TestDB. The value entered for the Confirm Password field should be the same as the value for the DB Password field. Click on Next to go to the next screen, as shown in the following screenshot:
[ 54 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 3
12. In this screen, fill in the values for the following configuration properties: °
Transaction Type: The type of transactions that this connection pool supports
°
Pool Min Size: The minimum number of connections in the pool
°
Pool Max Size: The maximum number of connections in the pool
°
Blocking Timeout: The time period, in milliseconds, for which a caller will wait to obtain a connection from the pool
°
Idle Timeout: The amount of time, in minutes, after which an idle connection will be closed In order to test connectivity to the database instance that you specified in the database pool configuration, you can use the Test Connection button. If you want to skip the test and deploy then click on the Skip Test and Deploy button. In case you want to see the Geronimo-specific plan for this database pool, you can use the Skip Test and Show Plan button.
13. In order to test connectivity to the database instance that you specified in the database pool configuration, you can use the Test Connection button. 14. If you want to skip the test and deploy the connection pool, then click on the Skip Test and Deploy button. 15. If you want to see the Geronimo-specific plan for this database pool, then you can use the Skip Test and Show Plan button. 16. Clicking on the Skip Test and Deploy button will deploy and create the connection pool, and you will be taken back to the first screen of the Database Pools portlet that lists all the active database pools.
Installing unlisted drivers
If you want to download and install a driver that is not available in the list of downloadable drivers shown in the Administration Console, you will need to go to the download site for that particular RDBMS or database driver vendor and manually download the driver to a temporary location on your hard disk. From that location, you can install the driver into the server repository by using the Repository portlet.
[ 55 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity
In order to open the Repository portlet, you need to click on the Repository link in the Services section of the Console Navigation pane. The Repository portlet is shown in the following screenshot:
You need to use the Browse button to select the File on the disk that you downloaded and then complete the Group, Artifact, Version, and Type fields. This will result in the file being copied to the path. Actually, in most cases, the Artifact, Version, and Type are automatically detected by the portlet. Consider the case shown in this example. The name of the driver file is postgresql-8.3-604.jdbc3.jar. On selecting the file by using the file viewer that pops up on clicking on the Browse button, the Artifact, Version, and Type fields are completed with the values shown in the screenshot. If we enter the Group as org. jdbc.postgresql, then the archive will be installed as org.jdbc.postgresql/postgresql8.3/604.jdbc3/jar. The actual JAR file will be present in the repository in the org/ jdbc/postgresql/postgresql-8.3/604.jdbc3 directory, and will be named postgresql-8.3-604.jdbc3.jar. You can also manually copy JAR files to the repository. However, while doing this, the directory structure and the name of the JAR file should be the same as shown, that is, the JAR file should be present in the repository at ///.jar.
Once the driver has been installed in the server repository, it can be referred to as a dependency inside a Geronimo deployment plan for the TranQL connector for that database. The generic TranQL connector can be used for wrapping the drivers of any JDBC database driver.
Using the Deploy New portlet
The Administration Console has a Deploy New portlet for deploying artifacts to the server. You can deploy new applications as well as new database pools or JMS connectors. In order to deploy a database pool using this portlet, you need to provide [ 56 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 3
the portlet with the required TranQL connector and the corresponding deployment plan. You can use the Browse button to locate the required TranQL RAR file from the server repository, as well as to locate the deployment plan. Deployment plans can be generated through the Administration Console Wizard as follows: 1. Go to the Database Pools portlet, and click on the Using the Geronimo database pool wizard link to bring up the wizard, as shown in the following screenshot:
2. Enter the Name of Database Pool, say DerbyTestPool, and select the Database Type, say Derby embedded XA. Click on Next to bring up the next screen, as shown in the following screenshot:
[ 57 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity
3. Select the Driver JAR file, as shown in the previous screenshot. For our example, it should be org.apache.geronimo.configs/system-database/2.1.4/car. We select a car for an embedded Derby database because Geronimo already has an embedded Derby instance running for the system database. Therefore, by choosing a dependency on that configuration, the Derby classes are not loaded again and a new embedded Derby instance is not created. Instead a new Derby database is created using the same embedded Derby instance. °
Complete the Database Name field with the value DerbyTestDB.
°
Set the Create Database flag to true. This will result in a new Derby database being created if one does not already exist.
°
Complete the User Name and Password fields with system and manager, respectively.
°
Select a Transaction Type of XA.
°
Click on the Show Plan button to show the deployment plan, as shown in the following screenshot:
[ 58 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 3
4. Copy the plan from the text area and paste it in a new file called plan.xml. The contents of the plan.xml file are shown in the following listing:
console.dbpool DerbyTestPool 1.0 rar
org.apache.geronimo.configs
system-database 2.1.4 car
javax.sql. DataSource
DerbyTestPool manager
D erbyTestDB system
10 0 [ 59 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity 5000 15
We will now go through the significance of the major elements in the plan: °
connectionfactory-interface: This should be javax.jms. ConnectionFactory.
°
name: The name that is used by other modules to refer to this
°
config-property-setting: This element is used to define properties that are specific to the resource adapter. The name of the property will be specified as the value of the name attribute and the value of the property will be given as the value of this element.
°
connectionfactory-interface: The interface that is implemented by the connection factory. This should be javax.sql.DataSource.
°
xa-transaction: Indicates that the resource adapter can participate in XA transactions.
°
transaction-caching: Indicates that connection sharing
°
single-pool: This specifies the connection pooling type, and
°
match-one: This is a connection pool match setting that
resource. The name should be unique across the scope (server or application) in which these resources are deployed. It is a good practice to have names that are unique across scopes.
must be enabled for resources in the same transaction.
means that a single connection pool will be used to pool all connections to this resource.
will select one connection from the pool and test whether it matches the connection request. If it does, then the connection is used. Otherwise, an error is thrown.
[ 60 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 3
5. Deploy the pool by using the connector \repository\
org\tranql\tranql-connector-derby-embed-xa\1.4\tranqlconnector-derby-embed-xa-1.4.rar and the path of the plan—that is, in
the Deploy New portlet enter the path of the TranQL RAR file in the Archive textbox and the path of the plan in the Plan textbox.
6. If you browse to the Database Pools portlet, then will now see this database pool listed.
Using the command-line deployer
In some distributions of Apache Geronimo, such as Little-G, the Administration Console is not present. You can also assemble a custom server without the Administration Console. In such an environment, you can still use the commandline deployer or GShell for deploying the database pools. Another instance where this is useful is when you have multiple servers on which you want to deploy the database pool. In this case, you can use the Administration Console Wizard to configure the database pool and generate a deployment plan on one server and use this deployment plan repeatedly on different servers, in order to deploy the database pool. In case you want to deploy your database pool from the command-line deployer, you need to follow the steps as follows: 1. Open the command line in Windows, or the shell in a Unix based OS, and change the directory to the /bin directory. 2. Next, invoke the deploy script from the bin directory. You need to provide the deploy script with the path to the TranQL RAR file and the deployment plan. 3. Assuming we are deploying the same database pool as the one in the previous section, the command will be deploy deploy where is the path to the TranQL RAR archive and the is the path to the deployment plan for that database pool. Assuming the plan file is saved to DerbyTestPool-plan.xml, the command would look like the following: deploy deploy \repository\org\tranql\tranql-connectorderby-embed-xa\1.4\tranql-connector-derby-embed-xa-1.4.rar DerbyTestPoolplan.xml
The JAVA_HOME or JRE_HOME should be pointing to a valid JDK or JRE in order to make the deployer scripts work.
[ 61 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity
Using GShell
You can also use Geronimo's command shell, 'GShell', for deploying the database pools. For doing this, you should first boot up GShell by running the gsh script (gsh.sh for a Unix-based OS, or gsh.bat for Windows). This will bring up the GShell prompt: @:/>
where is the username you use to log in and, is the hostname of the system. The command to deploy the database pool is deploy/deploy
GShell supports file separators of '/' and '\', but if the separator is '\', it should be escaped as '\\'. For example, C:\test\hello should be represented as C:\\test\\hello.
Creating an application-scoped database pool
An application-scoped database pool is visible only within the scope of the application. It is available to all of the modules that are present within an enterprise application (for example, war, ear, jar, and so on). It can also be made visible to other applications if they declare a dependency on the application containing the database pool. You can deploy an application-scoped database pool by adding an ext-module element to the application's Geronimo specific deployment plan.
To illustrate this, we have provided a sample application. This sample application is present at samples\Chapter-3 Database Connectivity\JDBC Sample ear. The ext-module section in the geronimo-application.xml file of the JDBC sample EAR application is shown below:
JDBCDataSource
org.tranql tranql-connector-derby-embed-xa
rar
[ 62 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
The sections with dashes are actually the same as those shown earlier in the plan.xml file. It has the following elements that are not present in the deployment plan for a server-scoped database connection pool: •
connector: Name of the connector.
•
external-path: Defines the TranQL resource adapter that will be used to deploy the connector plan. It consists of groupId, artifactId, type,
and so on, which are used to identify the resource adapter in the Geronimo repository.
After these two elements, the plan is identical to the one for the server-scoped database pool. Note that the dependencies present in the server-scoped plan are not present in the connector section of the application plan, as they are added as a dependency for the entire application. There is also no dependency on the database pool in the application plan, as it is contained in the application itself.
[ 63 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity
Creating a client-scoped pool
A client-scoped database pool is maintained by the Java EE client container, which runs in a JVM instance separate from the server. The database pool will be visible to the application client instance that runs inside this container. The client container will connect as a separate process to the database instance, and the database should be configured to accept connections from the client container. To illustrate, we have provided a sample application. This sample application is present at samples\ Chapter-3 Database Connectivity\JDBC Sample ear. The module plan for creating a client-scoped connection pool is shown below:
JDBCSample-client-1.0.jar
com.packtpub.jdbc JDBCSample-client 1.0 car
com.packtpub.jdbc JDBCSample-client-server 1.0 car
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 3
javax. sql.DataSource
DerbyTestPool manager DerbyTestDB localhost 1527 system
10 0 5000 15
The first part of the code defines the environment in which the client runs in the client container. It contains elements such as module ID, dependencies, and class loader. This is followed by the section for the server environment. This will define the environment on the server that is required for the application client, and identify it by using the module ID.
[ 65 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity
Note that in this plan, there is a resource section that contains the actual plan for the database connector. The additional element here is the external-rar element, which points to the TranQL RAR file in the server's repository that must be used to deploy this database connection pool. The remaining elements are the same as that of normal server-side resource adapter deployment plans. A slight difference is seen in the above plan, as we are using the TranQL client RA for derby that supports local transactions. We use the client RA as the database instance is in the server's JVM and we are connecting from a JVM instance that is separate to the one in which the client container is running.
Editing an existing pool
If you want to make changes to a database pool that you created, then you can either redeploy a database pool with the same name, or edit it from the Administration Console. Once you edit the fields from the Administration Console, you will need to restart the database pool configuration so that the changes can take effect. The steps for doing this are as follows: 1. Open the Database Pools portlet. This will bring up a list of database pools. 2. Click on the Edit link corresponding to one of the database pools that we created in previous sections, say DerbyTestPool. This will bring up a screen, as shown in the following screenshot:
[ 66 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 3
3. You can change any of the editable fields in this page, namely Database Name, Create Database, User Name, Password, Confirm Password, Login Timeout, Pool Min Size, Pool Max Size, Blocking Timeout, and Idle Timeout. 4. After editing the fields, you can then click on the Save button. The values will be saved, and you will be taken back to the screen showing the list of installed database pools.
Importing a pool from another application server
Apache Geronimo also provides mechanisms to reuse database pool configuration from other application servers such a JBoss and BEA Weblogic. In the following section, we will see how we can import a database pool from JBoss. Assume that we have a JBoss plan named test-ds.xml. This plan is provided in the samples\Chapter-3 Database Connectivity\jboss-plan directory. The contents of the plan are shown below:
TestDS jdbc:hsqldb:hsql://localhost:1701
org.hsqldb.jdbcDriver system manager 5 20 10
[ 67 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity
Go to the Database Pools portlet, and click on the Import from JBoss 4 link. This will bring up the next screen, which is shown in the following screenshot:
Use the Browse button to select the JBoss plan that you want to import. Next, click on the Next button to bring up the next screen, as shown in the following screenshot:
[ 68 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 3
Click on the Confirm and Deploy button to bring up the next screen, as shown in the following screenshot:
This screen will contain all of the details that are present in the JBoss deployment plan entered in the text boxes for the corresponding entries in the Apache Geronimo specific database pool deployment plan. Edit any field that you want to change, and then click on the Skip Test and Deploy button to deploy the database pool. You have now imported a database pool from JBoss and deployed it on Geronimo.
Creating an XA pool
Apache Geronimo supports the creation of XA database pools, which contain a pool of database connections that can join in XA transactions—that is, they can take part in a two-phase commit process. As there is a need for separate TranQL resource adapters for XA support for each database, Apache Geronimo supports XA with only a limited number of databases. [ 69 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity
The databases supported are: •
Apache Derby(Derby embedded XA, Derby network XA)
•
IBM DB2 (DB2 XA)
•
IBM Informix (In the works)
•
MySQL (MySQL XA)
•
Oracle (Oracle XA)
•
PostgreSQL (PostgreSQL XA)
In order to create an XA database pool, you need to select a database type in the Database Pools portlet as one of the above databases that have XA support, such as Derby embedded XA. The steps after selecting a database type are the same as that for local types except that the transaction type should be selected as XA. There may also be a few extra fields for XA connectors that need to be configured.
Using a database pool in an application
Once you have created a database pool, you can use it in your application to access the database that it provides connectivity with. Most applications other than the most trivial ones store data in databases and thereby require database access. In this section, we will walk through how we can configure an application to access a database through the database pool. We will look into how we can configure an application to use a server-scoped database pool as well as an application-scoped one. We will also see how we can configure an application to connect to the application-scoped database pool of a different application.
Accessing a server-scoped database pool
In order to access a server-scoped database pool from an application, you will need to give a dependency to the database pool in the application's Geronimo-specific deployment plan. We will illustrate this by using the JDBC sample application present in the directory of the samples for Chapter 3, Database Connectivity. The application consists of a servlet that connects to a database and then creates a table called CUSTOMER that consists of four columns. These columns are Name, Address, Phone, and Email. The application then inserts a record into the table.
[ 70 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 3
The application then retrieves that record and prints the details to your browser. The source code for the servlet is given as follows: package com.packtpub.cust; import java.io.*; import java.sql.Connection; import java.sql.ResultSet; import java.sql.Statement; import java.sql.SQLException; import javax.servlet.ServletException; import javax.servlet.http.*; import javax.sql.DataSource; import javax.annotation.Resource; public class CustomerInfoServlet extends HttpServlet { @Resource private DataSource ds; protected void service(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException { Connection conn = null; try { conn = ds.getConnection(); Statement stmt = conn.createStatement(); String createSQL = "CREATE TABLE CUSTOMER(Name char(50),Address char(50),Phone char(20),Email char(50))"; stmt.executeUpdate(createSQL); String insertSQL = "INSERT INTO TABLE CUSTOMER VALUES('Tom','Chapel Hill','234567','[email protected]')"; stmt.executeUpdate(insertSQL); ResultSet rs = stmt.executeQuery("SELECT * FROM CUSTOMERINFO"); res.setContentType("text/html"); PrintWriter out = res.getWriter(); out.print(""); out.print("Hello World Application "); out.println(""); out.println("
"); out.println("
"); out.print("
Name
"); out.print("
Address
"); out.print("
Phone
"); out.print("
Email
"); out.println("
"); while (rs.next()) { out.println("
"); [ 71 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
The DataSource, which is a connection factory to the connections in the pool, is obtained by resource injection. The @Resource annotation is used to specify that an instance of DataSource should be injected into this variable, as shown: @Resource private DataSource ds;
The connection is then obtained from the DataSource. A statement is created from the connection and then the executeUpdate method is called on the statement object to perform database operations, as shown: conn = ds.getConnection(); Statement stmt = conn.createStatement(); stmt.executeUpdate(createSQL); [ 72 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 3
The database plan that we will be using will be the same as the plan.xml file shown earlier. In case you have already deployed the plan, then you can deploy the application immediately. Otherwise, you will need to deploy the plan using the deployer, or the Deploy New portlet, as mentioned in the earlier sections on the deployment of database pools. After deploying the database pool, you will need to edit the geronimo-web.xml file of the application to have a dependency on the database pool, as well as a resource-ref element that maps the resource-refname to the database pool name. The plan is shown in the following illustration:
com.packtpub.cust CustomerInfo 1.0 car
console.dbpool DerbyTestPool
/CustomerInfo
jdbc/DataSource DerbyTestPool
You can see the dependency on the database pool, as well as the resource-ref mapping, in this web application plan. On deploying this application, it will be able to utilize the database pool named DerbyTestPool to connect to and interact with a Derby database instance.
[ 73 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Database Connectivity
Accessing an application-scoped database pool from the same application
In the case of an application-scoped database pool, the only difference is that there is no dependency on a database pool configuration. Instead, the database pool is defined in the application's deployment descriptor as a separate module. The mechanism to access the database pool in the application and the resource mapping in the deployment plan is same, as illustrated earlier in this section. Also you can add an application-scoped database pool only in an enterprise application. You cannot add it to standalone web or EJB applications. There is a sample application provided at samples\Chapter-3 Database Connectivity\JDBC Sample ear that is configured to use an application-scoped database pool. This application can be deployed by deploying the JDBCSample-ear-1.0.ear file, which is present in the modules\ear\target directory.
Accessing an application-scoped database pool from a different application
In the case of accessing an application-scoped database pool from a different application, the only difference is that the application that wants to access the database pool of a different application should have the application defining the database pool as its parent application—that is, it should have a dependency to the application defining the database pool.
Summary
In this chapter, we discussed the different options that Apache Geronimo provides to connect to relational database systems. We saw how to configure database pools of various scopes using different tools, such as the Administration Console, the command-line deployer, and GShell. We also took a peek into how we can import a database pool configuration from another application server, and how an enterprise application developer can configure an enterprise application to use the database pooling functionality provided by Apache Geronimo, for efficient database access. This covers most of the common things a Java EE developer using Apache Geronimo will need to know about database connectivity in order to enable him or her to use it to its fullest potential. In the next chapter, we will discuss the support provided by Geronimo for the Java Message Service (JMS). You will learn to configure the embedded JMS server, create JMS resources, and use JMS resources in Java EE applications.
[ 74 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
JMS Connectivity Java Message Service (JMS) is an important functionality that has to be provided by Java EE application servers. JMS enables the sending and receiving of messages by the Java EE application components. It allows these application components to communicate with other components (both Java and non-Java), which may be remote or local, in an asynchronous fashion, through messages. This communication is facilitated by the Message Oriented Middleware (MOM), also known as message brokers that implement JMS. Message brokers provide reliable delivery of messages between the application components. The message broker that is used in Apache Geronimo is Apache ActiveMQ, an open source message broker from the Apache Software Foundation �(ASF). ActiveMQ is an embeddable message broker that is written in Java. In this chapter, you will learn about the following: •
Configuring ActiveMQ, which is embedded in Apache Geronimo
•
Using a resource adapter to connect to the ActiveMQ broker
•
Creating new JMS connection factories, JMS queues, and JMS topics
•
Configuring application components to use the messaging functionality provided by the embedded Apache ActiveMQ
Message broker configuration
In this section, we will take a look at how the message broker is integrated into Apache Geronimo, and, look into the various configuration options that Apache Geronimo provides for configuring the Apache ActiveMQ message broker.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
JMS Connectivity
GBean configuration
The broker is instantiated and started in the org.apache.geronimo.configs/ activemq-broker/2.1.4/car configuration. This configuration has two GBeans.
ActiveMQ is the GBean that creates an instance of the broker and then starts it. The implementation class of this GBean is org.apache.geronimo.activemq. BrokerServiceGBeanImpl. This GBean only provides a few configuration attributes, but these attributes are enough to configure ActiveMQ. The attributes provided are as follows: •
brokerName: A name for this broker instance
•
dataSource: The JNDI name of the data source used for storing ActiveMQ message store data
•
dataDirectory: The directory where the ActiveMQ message store data is
•
brokerUri: The path of the broker configuration XML deployment descriptor
•
useShutdownHook: A Boolean value indicating whether the embedded ActiveMQ broker instance should use a shutdown hook or not.
stored. It is also used to store logfiles.
The values for these attributes, for the ActiveMQ GBean, can be found in the deployment plan for the broker configuration. This is shown below:
Ensure that the portlet-name matches the one in web.xml. 7. Once you have created these files, build the web application by invoking the following command from the ClockWebApp directory: mvn clean install
8. Deploy the WAR file created to the Apache Geronimo server where you had previously deployed the World Clock plugin.
[ 242 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 9
Once you log in to the Administration Console, you will notice a World Clock link at the bottom of the console navigation menu in the Other section. Clicking on it will bring up the page shown in the following screenshot:
Plugins portlet
The Plugins portlet enables a user to dynamically install new features into the Geronimo server, create plugins out of existing configurations on the server, and create server assemblies consisting of some or all of the existing plugins in the server. By using the Install Geronimo Plugins section, you can search for plugins in a plugin repository or add new repositories for plugin searches. You can also download running configurations from another Geronimo server, just as if you're browsing and installing third-party plugins by using the repository URL http://remote-geronimo-server:8080/plugin/maven-repo/ and providing the administrator username and password.
[ 243 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Plugins
In order to search for plugins, select the repository URL, and click on Show Plugins in selected repository. This will show all of the available plugins in that repository, as shown in the next screenshot:
A check mark in the Installable column for the plugin name indicates that the plugin is installable. You can click on the plugin name to view the details of the plugin. You can select one or more plugins, and click on Install to install the plugins. The portlet will show the status as the plugins are installing and display a confirmation message once completed. The Create Geronimo Plugin section lets you create a new plugin out of an existing configuration on the server. Select the configuration to be exported as a plugin, and click on the Export Plugin button. On the next page, you can fill in various details, such as Download Repositories that need to be looked in for downloading Dependencies, a Description of the plugin, the Geronimo Versions on which the plugin can be installed, JVM versions, the dependencies of this plugin on other configurations or artifacts, Prerequisite configurations, and so on. The fields have detailed explanation on this page. After completing the fields, click on Save Plugin Data. On the next screen, click on the Export Plugin button to save the plugin to filesystem. The configuration will be saved as a configuration archive (CAR) file. [ 244 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 9
Custom server assemblies and server profiles
Apache Geronimo provides a feature known as custom server assemblies. This allows users to assemble servers that are customized to their needs. They can assemble the application servers that contain their applications or plugins prepackaged with only the additional dependent modules that their applications or plugins require. We will go through the steps to assemble a custom server that contains the World Clock plugin as follows: 1. Log in to the Administration Console, and go to the Plugins portlet. 2. In the Assemble Server portlet, click on the Assemble a server button. This will bring up the screen shown in the following screenshot:
[ 245 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Plugins
3. Enter the groupId, artifactId, version, and the target path where the assembly should be saved under the directory, and select the required format. Select the plugins that need to be included in the assembly, and click on the Assemble button. Always select Geronimo Assemblies :: Boilerplate Minimal. Select the WorldClock plugin. The WorldClock plugin does not need any other Apache Geronimo's services, so we need not include any other assemblies. 4. Click on the Assemble button at the bottom of the screen. This will bring up the screen shown in the next screenshot:
5. Click on the Assemble button to assemble the custom server. Once the server assembly process is complete, a screen with the status and the location of the created assembly will pop up. 6. Now stop the current server, and start the server you just assembled. You will see that the WorldClock plugin is started, as the time will be printed out during startup. You can also assemble custom servers through deploy/assemble command in GShell.
[ 246 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 9
Summary
In this chapter, we saw how Apache Geronimo's plugin architecture provides the capability for users to extend the functionality of the server. We saw how we can develop a plugin and deploy it to the server. We also had a look at the pluggable administration console, and how to create and plug in a new Administration Console portlet. We also saw how Apache Geronimo allows users to export custom server assemblies. In conclusion, Apache Geronimo turns out to be a very modular, customizable, and flexible application server. In the next chapter, we will see how we can administer Apache Geronimo. We will look into administering the different resources, plugins, and applications that are deployed on the server, as well as other server configuration options.
[ 247 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration Java EE server administration can be a daunting task. Geronimo proves otherwise. Thanks to the Geronimo project's foremost guiding principle—ease of use, Geronimo provides a powerful and user-friendly Administration Console that simplifies various administrative tasks, be it administering the web container, managing the applications, or monitoring the server. In this chapter, we will go through the common administration tasks in an application server and see how these tasks are performed in Geronimo. You will learn about: •
The Administration Console
•
Web server administration
•
JMS server administration
•
Monitoring the server
•
GShell
Administration Console
The Administration Console is a very powerful and user-friendly web application that simplifies several aspects of administering Geronimo. After the Geronimo server has been started, the Administration Console can be launched by using the URL http://localhost:8080/console. The default username is system, with a password of manager.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
The welcome screen is shown in the next screenshot:
The Administration Console consists of several portlets based on the JSR 168 standard implemented by Apache Pluto. The Console Navigation pane on the left-hand side groups these portlets into different groups based on their function, for easy navigation. Server, Services, Applications, Security, Debug Views, and Embedded DB are the portlet groups in the Administration Console. You can add [ 250 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
new portlets and portlet groups to the extensible Administration Console by creating Administration Console extensions. Let us now examine each of the portlet groups and see what these portlets have to offer.
Server portlets
The portlets in the Server group allow you to manage server components such as the Web server, and JMS server, and monitor the JVM that is running the Geronimo server.
Information portlet
The Information portlet, as the name suggests, displays information about the server, such as the Version and Build of the Geronimo server, the server start and up times, details of the Operating System on which the server is running, details of the JVM version, and Server Memory Usage. The portlet screen is shown in the next screenshot:
[ 251 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
This portlet also provides a graph showing the current memory usage by the server.
Java System Info portlet
The Java System Info portlet displays the details of Java system properties set in the JVM that is running the server. The system properties are grouped into several groups, namely Java, Virtual Machine, Operating System, Sun, User, and Etc, for better presentation.
Server Logs portlet
The Server Logs portlet lets you view the server logs. This portlet features the following: •
Log Manager: Enables you to temporarily change the server log settings in the configuration file used by log4j, such as the refresh interval, and log level. Note that these changes will be effective only for the current run of the server. The log4j configuration file value can be overridden at server startup by using the org.apache.geronimo.log4jservice.configuration system property.
•
Server Log Viewer: Enables you to view the messages that have been logged to geronimo.log. You can also filter the messages based on the line number in the log file, the message log level, and lines containing a specified text, with or without exception details.
•
Web Access Log Viewer: Allows you to view the details of requests coming into the web container. You can also filter the messages based on a date range, requests coming in from a specified remote address, requests coming in from a specific logged in user, the request method (GET, POST, and so on.), the requested URI, and line numbers in the log. See the section Web Server Administration, for more details on the Web Access Log Viewer.
•
Derby Log Viewer: Allows you to view the database logs of the embedded Derby database. You can also filter the results based on line numbers and lines containing a specified text.
Shutdown portlet
The Shutdown portlet allows you to shut down a running server from the Administration Console. Note that shutting down the server will disable the Administration Console, and the Administration Console will not be available again until the server is re-started. Use this portlet with caution.
[ 252 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
Web Server portlet
The Web Server portlet allows you to view the web server statistics, and manage the network connectors for the web container: Start, Stop, Restart, Edit, or Delete existing connectors, and create new HTTP, HTTPS, and AJP connectors. See the section, Web Server Administration, for more details.
Thread Pools portlet
The Thread Pools portlet lists the thread pools defined in the server, and lets you monitor the thread pools.
Apache HTTP portlet
The Apache HTTP portlet walks you through the process of configuring access to Geronimo through the Apache HTTP server, by using the mod_jk.so Apache module. See, Chapter 12, Clustering, for more details on using this portlet.
JMS Server portlet
The JMS Server portlet allows you to monitor and manage the ActiveMQ JMS server embedded in Geronimo. You can start, stop, edit, or delete existing JMS network listeners, and create new tcp, stomp, vm, udp, and multicast JMS network listeners. See the section JMS Server Administration for more details on using this portlet.
Monitoring portlet
The Monitoring portlet allows you to monitor local and remote Geronimo servers by creating graphs for specific server attributes exposed through MBeans, and compose views consisting of graphs. See the section Monitoring the server for more details on using this portlet.
Services portlets
The portlets in the Services portlet group allow you to access the repository service and resource adapters for the database and JMS.
[ 253 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
Repository portlet
The Repository portlet displays the list of artifacts installed in the server's repository. It also allows you to install a new artifact into the repository. To see how an artifact can be used, click on the link provided over the artifact name. The portlet screen is shown in the next screenshot:
To upload an artifact to the repository, select the File option, under Add Archive to Repository. Complete the Group, Artifact, Version, and Type fields for the artifact, and click on the Install button. Note that the portlet may compute Artifact, Version, and Type values from the filename and populate these fields automatically. You can change these values as required. In the example in the above screenshot, once uploaded, the artifact will be available at libs/mylib/1.2/jar.
Database Pools portlet
The Database Pools portlet displays all of the database pools that are available on the server. This portlet also provides a wizard that will take you through a step-by-step process to create new database pools. See Chapter 3, Database Connectivity, for more details on using this portlet.
[ 254 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
JMS Resources portlet
The JMS Resources portlet displays all of the available JMS resource groups on the server. It also provides a wizard that can be used to add new JMS resources for ActiveMQ or any other JMS provider. See Chapter 4, JMS Connectivity, for more details on using this portlet.
Applications portlets
The portlets in the Applications group of portlets allow you to manage applications and services running on the Geronimo server. The administration tasks include installing new applications or services, starting, stopping, restarting, and uninstalling existing applications or services, installing plugins, creating plugins from configurations running in the server, assembling servers from the plugins in the current server, and so on. We will now go through the functions provided by various portlets in the Applications group.
Deploy New portlet
The Deploy New portlet allows you to install new applications and services on a Geronimo server. The portlet screen is shown in the screenshot below:
You can deploy an archive, a plan, or both. Select the archive file to be deployed in the Archive field, and/or the plan file in the Plan field. If the installed application or service is to be started once it has been installed, then select the option Start app after install (this option is selected by default). If the deployment step should replace an existing application or service with the same module ID as the one to be deployed, then select the Redeploy application option. Click on the Install button to complete the deployment operation.
[ 255 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
System Modules portlet
The System Modules portlet lists the configurations that form the core of Geronimo, and the configurations that deploy services such as security realms. Apart from listing the configurations, this portlet provides links to Start, Stop, Restart, and Uninstall individual configurations. Notice that the portlet disables links to Stop, Restart, and Uninstall some of the configurations. The links corresponding to the Geronimo-provided components are disabled to prevent accidental stopping of the configurations, which may prevent the server from starting, or disable the Administration Console. To enable all of the command links, select the Expert User checkbox. Select the Show parent and child components checkbox to display the direct parent and child configurations for each of the listed configurations.
Web App WARs portlet
The Web App WARs portlet lists all of the standalone web applications that are deployed in the server. The portlet provides links to Start, Stop, Restart, and Uninstall individual web applications. Notice that the portlet disables links to Stop, Restart, and Uninstall Geronimo-provided components. To enable all of the command links, select the Expert User checkbox. Select the Show parent and child components checkbox to display the direct parent and child configurations for each of the listed configurations. For each of the running web applications, the URL column provides a link to access that web application.
EJB JARs portlet
The EJB JARs portlet lists all of the standalone EJB applications that are deployed on the server. The portlet provides links to Start, Stop, Restart, and Uninstall individual EJB applications. Notice that the portlet disables links to Stop, Restart, and Uninstall Geronimo-provided components. To enable all of the command links, select the Expert User checkbox. Select the Show parent and child components checkbox to display the direct parent and child configurations for each of the listed configurations.
Application EARs portlet
The Application EARs portlet lists all of the enterprise applications that have been deployed on the server. The portlet provides links to Start, Stop, Restart, and Uninstall individual EAR applications. Notice that the portlet disables links to Stop, Restart, and Uninstall Geronimo-provided components. To enable all of the command links, select the Expert User checkbox. Select the Show parent and child components checkbox to display the direct parent and child configurations for each of the configurations listed. The URL column provides links to any web applications that are a part of the EAR application. [ 256 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
J2EE connectors portlet
The J2EE Connectors portlet lists the configurations that deploy database pools and JMS resources. The portlet provides links to Start, Stop, Restart, and Uninstall individual configurations. Notice that the portlet disables links to Stop, Restart, and Uninstall Geronimo-provided components. To enable all of the command links, select the Expert User checkbox. Select the Show parent and child components checkbox to display the direct parent and child configurations for each of the listed configurations.
App Clients portlet
The App Clients portlet lists all of the Java EE application clients that are deployed on the server.
Plan Creator portlet
The Plan Creator portlet lets you create a Geronimo deployment plan in a step-by-step process for deploying applications in Geronimo, and then deploy the application on the Geronimo server. This is a work-in-progress and the portlet in Geronimo v2.1.4 only supports web applications. In order to create a deployment plan, we select the Archive file, and then click on Configure. In the first step, you configure the environment for your application, such as the configuration ID, and the class loader settings such as Hidden Classes, Non Overridable Classes, and Inverse Class Loading. You also configure a context-root for your web application. Note that the portlet provides default values for many fields. After editing or completing the required fields, click on Next. In the second step, you configure EJB, EJB Local, JDBC Connection Pool, JavaMail Session, JMS Connection Factory, JMS Destination, and the Web Service references that your application is using. For each of the EJB references, the portlet provides a drop-down list containing all of the EJBs available on the server. For each JDBC Connection Pool resource reference, the portlet will provide a drop-down list with all of the DB Pools available on the server. All you need to do is select the resource to be mapped to for each of the references, and then click on Next. In the third step, you configure the Security elements, if your application is using security. You select the Security Realm and Create role-to-principal mapping for each of the security roles. In order to add a principal to a role, select a type of principal in the Add dropdown, select the principal class in the Class dropdown, specify the principal name in the Name field, complete in any additional fields, depending on the type of principal (for example, selecting Login Domain Principal will require you to fill in the domain name), and then click on Add. Repeat the procedure to add more principals to the role. [ 257 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
In order to specify the default Subject and run-as Subjects, select the Advanced Settings checkbox. Once that is done, click on Next to go to the next step. In the fourth step, you configure the Dependencies on existing configurations for your application. In this step, the portlet displays the list of configurations on the server. Note that the dependencies corresponding to the configuration that you have performed in the previous steps are automatically selected. You will only need to configure any additional dependencies in this step. Once that is done, click on Next to see the created plan. The portlet will display the created plan in an editable text area. At this stage, you can make any changes that you wish to make to the generated deployment plan. When you have finished, click on the Deploy WAR button to deploy your application with the generated plan. You may also save this plan to an external file and use the Deploy New portlet to deploy your application with the saved plan.
Embedded DB portlets
The portlets in the Embedded DB portlet group provide information on the Embedded Derby database server, and let you manage the databases on the server.
DB Info portlet
The DB Info portlet displays complete information regarding the database SystemDatabase on the Embedded Derby database server. The information displayed includes the version of Apache Derby, the Name and Version of the JDBC driver, the JDBC version level, the functions supported by the database, and so on.
DB Manager portlet
The DB Manager portlet enables you to manage the databases created in the Embedded Derby database server. The portlet screen is shown next:
[ 258 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
The DB Viewer lists the databases on the server. You can view the list of application tables, by clicking on the Application link listed under the View Tables column against the database name. You can view the list of system tables by clicking on the System link listed under the View Tables column against the database name. The following screenshot shows the application tables in SystemDatabase:
Click on the View Contents link provided against any table name to view the rows in that table.
[ 259 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
The Run SQL section allows you to create new databases, delete existing databases, and run SQL commands against an existing database. To create a new database, enter the database name in the Create DB field, and click on Create. To delete a database, select the database name in the drop-down list provided against Delete DB, and click on Delete. To run SQL, select the database name in the drop-down list provided against the Use DB field, enter the SQL text in the SQL Command/s field, and click on Run SQL. Use a semicolon to separate multiple SQL statements. Results will be displayed for a single Select statement.
Debug Views portlets
The portlets in the Debug Views portlet group let you examine the internal state of the Geronimo server without having to use any external tools.
JMX Viewer portlet
The JMX Viewer portlet allows you to connect to the Geronimo's MBeanServer and manage the MBeans without having to use an external monitoring and management console such as JConsole. The portlet screen is shown in the next screenshot:
[ 260 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
You can browse the MBeans, search for MBeans, view attributes, execute operations, and view MBean information and statistics. You can navigate to the MBeans by using the tree structure provided on the left. The Attributes tab displays the names and values of the attributes of the MBean selected on the left-hand side. The Operations tab allows you to invoke the operations exposed by the MBean. The Info tab provides the identity details of the MBean such as abstractName, objectName, j2eeType, and so on. The Stats tab displays the statistics for statisticsProvider MBeans. The Search tab allows you to search for MBeans by providing Object Name Pattern.
LDAP Viewer portlet
The LDAP Viewer portlet lets you connect to an LDAP server and browse the LDAP directory. The portlet screen is shown in the next screenshot:
In the Connection Info tab, complete the following fields: •
Host: The hostname or IP address of the LDAP server.
•
Port: The port on which the LDAP server is running.
•
Version: Select the version of the LDAP protocol being used.
•
Base DN: The top level of the LDAP directory tree.
•
SSL: If you select this option, then the port is SSL-enabled.
•
Anonymous Bind: Select this option if the connection to the LDAP server should be anonymous. Otherwise, complete the User DN and Password fields.
•
User DN: The distinguished name of the user to use when connecting to the LDAP server.
•
Password: The credentials of the user specified in the User DN field, for connecting to the LDAP server. [ 261 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
Click on Connect to connect to the LDAP server. Once connected, you can navigate through the directory tree. The following screenshot shows the directory entry for uid=admin, ou=system:
The Attributes tab shows the various attribute names and values of the directory entry selected in the tree on the left. You can search the directory by using the Search tab, as shown in the next screenshot:
Complete the following fields: •
Search DN: The distinguished name to search for.
•
Filter: The filter criteria for the results matching the search DN.
•
Search scope: Select One level if the matching entries have to be directly below the base. Select Sub-tree level to match entries at any level in the directory tree.
Click on Search to view the entries matching the specified criteria. [ 262 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
ClassLoader Viewer portlet
With multiple class loaders in a Java EE application server, instances of ClassNotFoundException, NoClassDefFoundError due to classes not loaded, classes loaded into multiple class loaders, and classes not available for loading can become a debugging nightmare for developers. The ClassLoader Viewer portlet allows you to search for classes loaded in the various class loaders in JVM running on the Geronimo server. The portlet screen is shown in the next screenshot:
The portlet displays the class loaders as a tree, starting with the JVM's extensions class loader at the root. For each class loader, expand the Classes child to view the classes currently loaded. Expand the Interfaces child to view the interfaces currently loaded. Next to the Interfaces is the list of all of the child class loaders of that class loader. Expand the child class loader entries to further browse the classes, interfaces, and their child class loaders. Geronimo uses a multi-parent class loader architecture. With this, it is possible that a class loader has more than one direct parent. The ClassLoader Viewer portlet provides the ability to invert the class loader tree so that all of the direct parent class loaders are displayed with each class loader.
[ 263 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
The following screenshot shows the inverted class loader tree for a database pool:
Notice that in this example, the console.dbpool/LibraryDS/1.0/rar class loader has three direct parent class loaders with IDs: org.apache.geronimo.configs/j2eeserver/2.1.4/car, org.apache.geronimo.configs/system-database/2.1.4/car, and org.apache.geronimo.configs/transaction/2.1.4/car. Furthermore, the org.apache.geronimo.configs/system-database/2.1.4/car class loader has three direct parent class loaders with IDs: org.apache.geronimo.configs/ derby/2.1.4/car, org.apache.geronimo.configs/j2ee-server/2.1.4/car, and org.apache. geronimo.configs/transaction/2.1.4/car. In order to search for a class, enter the class name in the Search Text field and click on Find. To find the next result, click on Find Next. To restrict the search to a selected part of the tree, click on the element, and then Search only selected.
[ 264 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
JNDI Viewer portlet
The JNDI Viewer portlet allows you to view the various resources bound to JNDI in the Global Context, along with the context of each of the artifacts, such as servlets, EJBs, web modules, EJB modules, resource adapter modules, and enterprise applications. The portlet screen is shown in the next screenshot:
[ 265 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
The following screenshot shows the JNDI names bound in the context of a session bean and a web application.
Note the JNDI entries bound in the context of LibraryBean in the EJB application packt.samples/cmp-jpa-ejb/1.0/jar shown above. You can also see the JNDI entries bound in the context of the web application org.apache.geronimo.plugins/ mconsole-tomcat/2.1.4/car. You can search for a specific text. To do this, enter the text in the Search Text field, and then click on Find. If the text search is to be case sensitive, then select the Case Sensitive option. If you want to restrict the search to a selected sub-tree, then select the Search only selected option.
[ 266 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
Dependency Viewer portlet
The Dependency Viewer portlet lets you view the dependencies between various configurations deployed on the Geronimo server, and also list the artifacts in the repository. The portlet screen is shown in the next screenshot:
You can browse the configurations of various enterprise applications, EJB applications, web applications, resource adapters, application clients, and system modules deployed on the server. For each of the configurations, expand the dependencies to view the parent configurations and dependencies on the artifacts in the repository. You can also perform a text search by entering the text in the Search Text field, and then clicking on the Find button. Click on Find Next to search for the next occurrence of the text. Select the Search only selected option to restrict the search to a selected sub-tree.
[ 267 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
Web Server administration
The Web Server portlet in the Server portlet group allows you to manage the network connectors for the web container, and view web server statistics. In this section, we will see how the Web Server portlet can be used to perform various web server administration tasks. The Web Server portlet screen is shown in the next screenshot:
The portlet lists the existing network connectors for the web container. The Protocol column displays the protocol used by the connector. The links provided in the Actions column allow you to manage the connectors. To stop a running connector, click on the Stop link under Actions. To start a stopped connector, click on the Start link under Actions. To stop and start a running connector, click on the Restart link under Actions. The Restart link is particularly useful when you want to restart a connector that is listening on the same port as the one on which you are accessing the Administration Console application. To edit the settings of a connector, click on the Edit link under actions. The next screen will show the connector attributes. Edit the attributes as necessary, and then click on Save to return to the Network Listeners screen. Note that any changes to a network connector will not take effect until the connector is started again, either by using Restart, or Stop and then Start. To delete an existing connector, click on the Delete link under Actions, and confirm the deletion in the pop-up dialogbox. For a Tomcat web container, you can add blocking IO (BIO), non-blocking IO (NIO), and Apache Portable Runtime (APR) connectors for the HTTP and HTTPS protocols. To add new connectors to the Tomcat web container, use the links provided under Add new section.
[ 268 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
HTTP connectors
To add a new BIO HTTP connector, click on the Tomcat BIO HTTP Connector link. This will show a screen similar to the one shown in the next screenshot:
The Attribute column shows the name of the attribute. The Type column shows the attribute type. The Value column provides a field in which you can enter a value for the attribute. The Description column gives a detailed description of the attribute. Required attributes are indicated by an asterisk. For a BIO HTTP connector, the following attributes are required: •
uniqueName: A name to identify the connector. This name has to be different from the name of any other web connectors on the server.
•
address: Host name or IP address to bind the connector to. Common values are 0.0.0.0 (all interfaces) or localhost (local connections only).
•
port: The TCP/IP port to which the connector will be bound.
[ 269 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
Enter the values for these required attributes. The remaining fields are optional, and most fields are populated with the default values. You may edit or enter values for the optional fields, as necessary. Once that is done, click on Save to create a new BIO HTTP connector and return to the list of connectors. The newly-added connector will be started automatically. To add a new NIO HTTP connector, click on the Tomcat NIO HTTP Connector link under the Add new section. Enter the required attributes: uniqueName, address, and port. The remaining attributes are optional and most of them are populated with default values. Edit or enter the values for these optional attributes as necessary. Once that is done, click on Save to create a new NIO HTTP connector, and return to the list of connectors. The newly-added connector will be started automatically. To use APR connectors for a Tomcat web container, you will need to install the APR native components. See the Tomcat documentation, available at http://tomcat.apache.org/tomcat-6.0-doc/apr.html, for details on installing the components required for APR. Once the APR components are installed, you can create APR connectors. In order to add a new APR HTTP connector, click on the Tomcat APR HTTP Connector link under the Add new section. This will show a screen, similar to the one shown in the next screenshot:
[ 270 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
Enter the required attributes: uniqueName, address, pollTime, pollerSize, port, sendfileSize, and useSendfile. Here, the attributes pollTime, pollerSize, sendfileSize, and useSendfile are APR-related attributes. The default values of attributes are populated automatically. Edit or enter the values for all of the attributes. When finished, click on Save to create a new APR HTTP connector, and return to the list of connectors. The newly-added connector will be started automatically.
HTTPS connectors
For HTTPS connectors, you will need to configure the SSL-related attributes in addition to the attributes for an HTTP connector. To create a BIO HTTPS connector, click on the Tomcat BIO HTTPS Connector link under the Add new section. This will show a screen similar to the one shown in the screenshot below:
[ 271 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
The additional attributes related to SSL configuration are: •
keystoreFile: The file that holds the keystore. The value for this attribute is the path of the file relative to the directory.
•
algorithm: The certificate encoding algorithm to be used. Set this to Default so that the connector does not need to be reconfigured if the server is started with a different JVM.
•
ciphers: A comma-separated list of the encryption ciphers that may be used. If not specified, then any available cipher may be used.
•
clientAuth: Set to true if you want SSL to require a valid certificate chain from the client before accepting a connection.
•
keyAlias: The alias used for the server certificate in the keystore. If not specified, then the first key read in the keystore will be used.
•
keyStorePass: Set the password used to access the keystore file. This is also the password used to access the server private key within the keystore (so the two passwords must be set to be the same on the keystore).
•
keyStoreType: Set the keystore type. Normally, this is set to the default JKS.
•
sslProtocol: This should normally be set to TLS, although some (IBM) JVMs don't work properly with popular browsers unless this attribute is set to SSL.
•
trustStoreFile: The trust store file used to validate client certificates. The value for this attribute is the path of the file relative to the directory.
•
truststorePass: The password to access the trust store.
•
truststoreType: Set the keystore type of the trust store file. Normally, this is set to the default JKS.
The truststoreFile, truststorePass, and truststoreType attributes are only required if clientAuth attribute is set to true. In addition to the uniqueName, address, and port attributes, enter the values for the SSL-related attributes as well as the attributes required for an HTTP connector. When you have finished, click on Save to create a new BIO HTTPS connector, and return to the list of connectors. The newly-added connector will be started automatically. An NIO HTTPS connector can be created in a similar manner by completing the above SSL-related attributes in addition to the normal connector attributes.
[ 272 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
AJP connectors
To create a new AJP connector, click on the Tomcat AJP Connector link under the Add new section. This will show a screen similar to the one shown in the next screenshot:
For an AJP connector, the following attributes are required: •
uniqueName: A name to identify the connector. This name has to be different from the name of any other web connectors on the server.
•
address: Hostname or IP address to bind the connector to. Common values are 0.0.0.0 (all interfaces) or localhost (local connections only).
•
port: The TCP/IP port to which the connector will be bound.
Enter the values for these required attributes. The remaining fields are optional, and most fields are populated with default values. You may edit or enter values for the optional fields as necessary. When finished, click on Save to create a new AJP connector and return to the list of connectors. The newly-added connector will be started automatically.
[ 273 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
Web Server Logs
The Server Logs portlet in the Server portlet group provides a Web Access Log Viewer. The portlet screen is shown below:
You can filter the access logs by date range, the identity of the user accessing the web container, the request method and URI, and can also limit number of results to display. The following is a description of each of the fields: •
From (MM/DD/YYYY): The start date of the log entries to search for.
•
To (MM/DD/YYYY): The end date of the log entries to search for.
•
Ignore Dates: Select this to ignore the dates in the search criteria.
•
Remote Address: The remote address from which the web request is received.
•
Authenticated User: The authenticated username from which the web request is received.
[ 274 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
•
Request Method: The HTTP request method for the web request. Supported values are GET, PUT, POST, DELETE, and ANY. Select ANY to ignore the request method in the search.
•
Requested URI: The URI of the resource requested. The value entered here will be mapped to the start of requested URIs in the web request.
•
Start Result: The line number in the logfile from which the log entries are to be searched.
•
Max Results: The maximum number of log entries to be displayed.
Enter the values for the required fields, and then click on Filter Log to activate the filter criteria for the first time. To search for the logs once again with the same criteria, click on Refresh.
JMS server administration
Apache Geronimo integrates Apache ActiveMQ as a JMS provider. In this section, we will see how to administer the ActiveMQ server embedded in Geronimo.
JMS listeners
The JMS Server portlet in the Server portlet group enables you to manage the existing JMS Network Listeners and create new network listeners for ActiveMQ. The portlet screen is shown below:
[ 275 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
The JMS Network Listeners section lists the existing network listeners. By default, Geronimo provides listeners for the stomp and tcp protocols. You can stop, start, edit, or delete existing listeners by clicking on the corresponding links provided in the Actions column against a connector name. Note that any changes made to a listener that is running will not take effect until that listener is stopped and restarted. You can create new network listeners for ActiveMQ by clicking on the links provided under Add connector to ActiveMQ. You can create listeners for tcp, stomp, vm, udp, and multicast protocols. For example, to create a new listener for the tcp protocol, click on the Add new tcp listener link. This will display a screen similar to the one shown below:
Enter a Unique Name for the listener, the Host, and Port to bind the listener to, and then click on Save. This will add a new JMS network listener with the tcp protocol for ActiveMQ.
Monitoring the server
The Monitoring portlet in Server portlets group allows you to monitor a local or a remote Geronimo server. The console is designed to monitor a Geronimo instance running in a separate JVM. The console can gather statistics and performance data from multiple Geronimo servers, and display this data graphically. The Monitoring console uses the Management EJB (MEJB) to gather statistics from a remote Geronimo server. You may also use JMX to gather statistics from a remote server, but this would require the remote server to install and run the org.apache.geronimo.plugins. monitoring/agent-car-jmx/2.1.4/car plugin. The portlet screen is shown below:
[ 276 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
The Monitoring console defines Servers and Graphs with statistics collected from servers, and Views consisting of one or more graphs. In this section, we will see how the Monitoring console plugin can be used to monitor a Geronimo server.
Adding a Server
To add a server for monitoring, click on the Add a new server link. This will show a screen similar to the one shown below:
Complete the following fields: •
Name: A name to identify this server.
•
IP/Hostname: Hostname or IP address of the server to be monitored.
•
Protocol: Select EJB to use the MEJB. Select JMX to use the JMX server in the remote JVM.
•
Port: The port number to connect to the server. The default port number is 4201 for EJB and 1099 for the JMX protocol.
•
Username: The administrator username of the remote server.
•
Password: The password for the username entered above.
[ 277 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
Click on Add to complete adding this server. The newly-added server will be listed under Servers, as shown in the screenshot below:
The server is enabled by default. In order to disable the server, click on the Disable link under the Actions column. To edit an existing server, click on the Edit link under Actions. On the next screen, after editing the fields, click on Save to save your changes. A text of Online in the Status column indicates that the Monitoring console is able to connect to the server. Data collection is disabled by default. Enable data collection by clicking on the Enable Query link under actions. After enabling data collection, click on the link provided in the Name or IP/Hostname column to view the live statistics for chosen MBeans, as shown in the next screenshot:
[ 278 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
The Statistics Collected column shows the MBeans that are enabled for statistics collection. The Statistics Available column shows the MBeans that can be enabled for statistics collection. To disable statistics collection, click on the X next to the MBean name in the Statistics Collected column. To enable statistics collection, click on the + next to the MBean name under the Statistics Available column.
Adding a Graph
To add a graph, click on the Add a new graph link. This will display a screen similar to the one shown in the next screenshot:
Complete or select the following fields: •
Server: Select a server from which the statistics will be collected.
•
Name: A unique name for the graph.
•
Description: A description for this graph.
•
X axis label: A label for the horizontal axis.
•
Y axis label: A label for the vertical axis.
•
Timeframe: A time frame for the graph. [ 279 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
•
Mbean: The Mbean on the server that will provide the statistics.
•
Data series: Select As-is for the value as it is or Change (Delta) in for the difference. Select the statistic.
•
Math operation: Select an operation to combine more than one statistic for the graph.
•
Data series2: Select As-is for the value as it is or Change (Delta) in for the difference. Select the statistic.
Click on Add to add the new graph. The new graph will be shown under Graphs. To edit the graph, click on the Edit link under the Actions column. Click on the graph name to view the graph in a pop-up window.
Creating a new view
You can create a view consisting of graphs. In order to create a view, click on the Create a new view link. This will display a screen similar to the one shown below:
[ 280 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
Complete the Name and Description fields for the view, and select the Graphs to be displayed in the view. Click on Save to add the view. The new view will be shown under Views. To edit a view, click on the Edit link provided under the Actions column. Click on the view name to see the graphs in the view. The following screenshot shows a sample view:
This view shows two graphs. The first graph shows the current heap proportion to max heap size over time. The second graph shows the current heap size over time. Note that you can also compose views consisting of graphs from different servers.
[ 281 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
GShell
GShell is a command-line processor for creating command-line applications for administering the Geronimo server. GShell supports command editing, command history, I/O redirection, and so on. Geronimo administration commands such as startup, shutdown, and deploy are implemented by using GShell. In this section, we will see how GShell can be used to administer a Geronimo server.
Starting and exiting GShell
GShell can be started by using the script file gsh provided in the /bin directory. The GShell window is shown below:
[ 282 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
The quit or exit command will exit from the GShell environment.
Getting help
Use the help command to get a list of supported commands. To get help on any command, use the --help option with that command. The following screenshot shows help for the geronimo/start-server command:
The first column shows the long and short form of each option, and the second column provides an explanation of the option.
Supported commands
The GShell environment supports the following commands: •
geronimo/start-server: Starts a Geronimo server. If the --background option is not used, then the server will run in the shell, and you will need to open another shell to interact with the server.
[ 283 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
•
geronimo/stop-server: Stops a Geronimo server. Use the --hostname and --port options to specify the RMI host and port of the server to be stopped.
The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
•
geronimo/start-client: Starts an application client. Specify the configuration name of the application client and the application client arguments on the command line.
•
geronimo/wait-for-server: Waits for the start of a Geronimo server to complete the startup. Use the --hostname and --port options to specify
the RMI host and port of the server to be stopped. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options. •
deploy/connect: Connects to a running Geronimo server such that further deploy commands will not require the host, port, username, and password to be specified, until disconnected. Use the --hostname and --port options to specify the RMI host and port of the server to connect to. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
•
deploy/disconnect: Disconnects a Geronimo server that was connected earlier by using deploy/connect.
•
deploy/distribute: Executes the distribute deployer operation. Specify the module and plan files as arguments. Use the --inPlace option to specify in-place deployment. Use the --targets option to specify the deployment target configuration stores. Use the --hostname and --port options to
specify the RMI host and port of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options. •
deploy/restart: Restarts a running configuration and any running child configurations. Specify the configuration ID as an argument. Use the --hostname and --port options to specify the RMI host and port of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
[ 284 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
•
deploy/install-plugin: Installs a plugin into the Geronimo server. Specify the plugin file as an argument. Use the --hostname and --port options to specify the RMI host and port of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
•
deploy/deploy: Deploys the specified module and/or plan file. Specify the module and plan files as arguments. Use the --inPlace option to specify in-place deployment. Use the --targets option to specify the deployment target configuration stores. Use the --hostname and --port options to
specify the RMI host and port of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options. •
deploy/redeploy: Redeploys a specified module and/or plan file. Specify the module file, plan file, and the configuration ID as arguments. Use the --hostname and --port options to specify the RMI host and port of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
•
deploy/undeploy: Uninstalls a specified configuration. Specify the configuration ID as an argument. Use the --hostname and --port options to specify the RMI host and port of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
•
deploy/list-modules: List the configurations deployed on the server. Use the --hostname and --port options to specify the RMI host and port
of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
•
deploy/install-library: Installs a specified library file in the repository. Specify the group ID by using the --groupId option. Artifact ID, version, and type will be determined based on the file name. Use the --hostname and --port options to specify the RMI host and port of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
[ 285 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Administration
•
deploy/list-targets: Lists the available target configuration stores on the server. Use the --hostname and --port options to specify the RMI host and
port of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
•
deploy/stop: Stops a specified configuration and any child configurations
that are running. Specify the configuration ID as an argument. Use the
--hostname and --port options to specify the RMI host and port of
the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
•
deploy/start: Starts a specified configuration and any parent configurations
•
deploy/list-plugins: Lists the available plugins in a plugin repository. Specify the repository URL by using the --repository option. Use the option --refresh-list to refresh the plugin list. Use the option --refreshrepository to refresh the repository. This is an interactive command. If a
that are currently not running. Specify the configuration ID as an argument. Use the --hostname and --port options to specify the RMI host and port of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
repository is not specified, then you will be able to select a repository from the plugin repositories that have been added to the server. Once the list of plugins is displayed, you will have the option to install the plugins by providing the number in the displayed list. Use the --hostname and --port options to specify the RMI host and port of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options. •
deploy/assemble: Assembles a server from the current server with some or
all of the configurations on the current server. Specify the group ID, artifact ID, and version by using the --groupId, --artifact, and --version options. Specify an archive format of .zip or tar.gz by using the option --format. Use the --path option to specify the location of the assembly relative to the directory. Use the --hostname and --port options to specify the RMI host and port of the target server. The default values are localhost and 1099. You will be prompted for the username and password if you have not specified the credentials by using the --username and --password options.
[ 286 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 10
•
deploy/login: Saves the username and password for this connection so
that further deployment operations to this connection will not require the user credentials to be specified. Use the --hostname and --port options to specify the RMI host and port of the target server. The default values are localhost and 1099. Use the --username option to specify the username and --password option to specify the password.
•
jaxws/wsimport: Generates JAX-WS artifacts from WSDL. Run the command with the --help option to get detailed information on running the command.
•
jaxws/wsgen: Generates JAX-WS artifacts from a class. Run the command with the --help option to get detailed information on running the command.
The following are some general purpose commands supported by GShell: • • • • • • • • • • •
source: Loads a file or URL into the current shell. Use this command to
execute a command script that has been saved to a file. set: Sets a variable. unset: Unsets a variable. help: Shows the online help for a command. clear: Clears the terminal screen. ?: Alias for help. echo: Echoes or prints arguments to STDOUT. quit: Alias for exit. exit: Exits the shell. . (dot): Alias for source. print: Alias for echo
These commands can be used to create rich command scripts to administer a Geronimo server.
Summary
In this chapter, we have seen how various portlets in the Administration Console simplify administrative tasks such as managing web server connectors, managing applications, managing databases and JMS resources, monitoring the server, and viewing the logs. We have also gone through the features of GShell, which provides a scripting environment to manage a Geronimo server. In the next chapter, we will discuss the Geronimo Eclipse Plugin. You will learn how to install the Geronimo Eclipse Plugin in Eclipse IDE and how to develop, deploy, and debug Java EE applications on the Geronimo server. [ 287 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Eclipse Plugin The Geronimo Eclipse Plugin (GEP), as the name suggests, is a plugin for the Eclipse framework that extends the web tools framework provided by Eclipse to provide support for Apache Geronimo-specific artifacts. The GEP is a power tool for application developers who want to rapidly develop, deploy, test, and debug their applications in the development and test environment that is provided by the plugin. GEP does this by integrating Eclipse, the Web Tools Platform (WTP), and Apache Geronimo to provide an IDE with a rich feature set that leverages the features of each of its constituent components. The Geronimo Eclipse Plugin also provides developers with a comprehensive set of deployment plan editors that greatly simplify the process of creating Apache Geronimo-specific deployment plans for Java EE artifacts that you want to deploy on the server. The Geronimo Eclipse Plugin is an important component in driving the adoption of Apache Geronimo by making Java EE 5 development and troubleshooting easier for users of the Apache Geronimo application server. In this chapter, we will introduce you to Eclipse and the Web Tools Platform, and then guide you through installing the Geronimo Eclipse Plugin onto Eclipse with WTP. We will then go through the various features of the GEP and finally show how to develop the sample application, by using the Geronimo Eclipse Plugin. The topics discussed are as follows: •
Eclipse and web tools framework
•
GEP download and installation
•
Developing an application using GEP
•
Deploy, and run or debug the application in Geronimo
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Eclipse Plugin
Eclipse and the web tools framework
Eclipse is an open source Integrated Development Environment (IDE) from the Eclipse Foundation. It is an IDE written mostly in Java but not limited to being an IDE for Java. It supports a variety of languages like C, C++, Groovy, Java, and so on, by means of plugins. It is based on the OSGi framework. Eclipse is one of the most popular and widely-used IDEs for Java developers. It is also used by many third party vendors as the base for their commercially available IDEs, which actually are Eclipse, bundled with their custom plugins. The Eclipse community also develops and maintains a rich ecosystem of open source plugins for the base Eclipse IDE, as subprojects. One of these subprojects is the Web Tools Platform, which extends Eclipse with a set of features that are commonly required for Java EE development. It provides source and deployment descriptor editors for editing a variety of Java EE artifacts, as well as wizards for creating common Java EE components. It also provides tools for the deployment, testing, and debugging of Java EE applications on various application servers, as well as extension points for creating plugins for other application servers.
Download and installation
You can download Eclipse from the Eclipse Foundation’s web site http://www.eclipse.org. The latest released version of the Eclipse IDE , as of the time of writing, is Eclipse Ganymede. After installing Eclipse, you will need to download and install the Web Tools Platform on top of Eclipse. Otherwise, you can download an Eclipse version that includes the Web Tools Platform from the link http://www.eclipse.org/downloads/packages/. Select the Eclipse IDE for Java EE developers link to download the Eclipse IDE along with the Web Tools Platform. Ensure that you download the above-mentioned Eclipse package, as it contains all of the plugins that are prerequisites of the Geronimo Eclipse Plugin. For the Windows platform, the download will be provided as a ZIP archive. Extracting it will create a directory called eclipse. Open the eclipse directory and run the eclipse.exe executable, to bring up the dialog box shown below. If you are using a Unix-based platform (for example, Linux or Mac OS), the steps will be slightly different, and you would need to download the package for that particular platform. You would then need to extract the tar.gz or tar.bz2 archive to a directory represented by $ECLIPSE_HOME. You will need to invoke $ECLIPSE_HOME/eclipse in order to bring up a dialog similar to the one shown next:
[ 290 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 11
Click on OK to bring up the workspace. This will take you to the welcome screen. Click on the workbench icon to open up the workbench, where you can create and develop Java EE 5 artifacts. This is shown in the following screenshot:
[ 291 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Eclipse Plugin
GEP download and installation
We have already downloaded and installed the prerequisites for the Geronimo Eclipse Plugin, namely: •
JDK 1.5
•
Eclipse IDE for Java EE (Ganymede or Europa), which includes WTP
•
Apache Geronimo application server
Follow the steps below to install GEP: 1. Launch Eclipse, to bring up the workspace, as shown in the previous screenshot. Eclipse will be launched with the Java EE perspective by default. 2. In the bottom of the rightmost pane, select the Servers tab, and right-click on New | Server. This will bring up the screen that is shown in the next screenshot:
[ 292 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 11
3. Click on the Download additional server adapters link to bring up the Install New Server Adapter dialog box, as shown in the next screenshot:
4. Select Geronimo v2.1 Server Adapter, and then click on Next. 5. Read and Accept the license agreement, and then click on Finish. 6. You will see a dialog box, informing you that support for Apache Geronimo will be installed. Click on OK to start the download and installation of the Geronimo Eclipse Plugin. After installation, Eclipse will be restarted, and you will again need to select the workspace to bring up the workbench. Continue with the next steps to create a Geronimo Server instance.
[ 293 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Eclipse Plugin
7. In the Servers tab in the lower-right pane, select New | Server. This will bring up the screen shown in the following screenshot:
[ 294 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 11
8. Expand Apache, select Apache Geronimo v2.1 server, and then click on the Next button. This will bring up the screen shown in the next screenshot:
9. Enter the Application Server Installation Directory as , and select the correct JRE from the list of Installed JRE. Click on Next to bring up the next screen, or click on Finish to complete the installation. If you click on Finish, then you can skip the remaining steps. 10. If you click on Next, then you get the next screen where you can specify the location of the Apache Geronimo source code so that you can step through the Geronimo source code as well, when debugging your application. This is shown in the next screenshot:
[ 295 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Eclipse Plugin
11. Clicking on the Next button will bring up a window where you can specify the Hostname, Administrator id, and Administrator password. The fields will be populated with default values. It will also show the RMI Naming and Web Connector ports. This is shown in the next screenshot:
[ 296 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 11
12. Click on Finish, and an instance of the Apache Geronimo application server will be created in your workspace. 13. You can right-click on the server to bring up a list of options, including Start and Stop. Select Start in order to start the instance. On starting the server, the state of the server, displayed in Eclipse, will change to started. This is shown in the next screenshot:
[ 297 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Eclipse Plugin
Developing an application in GEP
We will now go through the steps that are involved in developing an enterprise application using the Geronimo Eclipse Plugin. We will use Java EE components from an existing sample application for our convenience, namely LibraryApp, which we saw in Chapter 5. The steps are as follows: 1. Firstly, we will need to create the project in Eclipse. For doing this, right-click on the project explorer tab on the left-hand side of the workbench, and select New | Enterprise Application Project. This will bring up the EAR Application Project window, as shown in the next screenshot:
2. Enter the Project name as LibraryApp, and click on Next. The next screen that comes up shows the Java EE Module Dependencies. This is shown in the following screenshot:
[ 298 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 11
3. Click on the New Module button to bring up the Create default Java EE modules window, as shown in the next screenshot:
[ 299 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Eclipse Plugin
4. Deselect the Create default modules checkbox to get options to create specific modules. By default, one module of each Java EE type is selected to be created. Click on Finish. 5. On the next screen, select the Create deployment descriptor checkbox, and click on Next to finish creating the application structure. This is shown in the next screenshot:
You will now have the application created with both Java EE 5 descriptors and Apache Geronimo-specific deployment plans.
[ 300 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 11
6. Clicking on the Apache Geronimo-specific deployment plan will bring up the deployment plan editors for that specific plan. The deployment plan editor for the plan of the application client module is shown in the next screenshot:
Note that the generated plans have certain fields filled in automatically. Now we can go through developing the application, as explained in the next steps.
[ 301 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Eclipse Plugin
7. Firstly, we will create the EJB in the application, namely MailBean. Right-click on the EJB project, namely, LibraryAppEJB and select new -> Session Bean. This will bring up the pop-up window shown in the next screenshot:
8. Complete the fields, as shown in the screenshot, and click on Finish to create the EJB and its remote and local interfaces.
[ 302 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 11
9. Similarly, to create a Servlet, right-click on the Web project LibraryAppWeb, and select New | Servlet to bring up the pop-up window shown in the next screenshot:
10. Enter the fields, as shown in the above screenshot, and click on Next to bring up the Create Servlet screen, as shown in the next screenshot, where you can enter the URL mappings and initialization parameters:
[ 303 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Eclipse Plugin
11. Click on Next to add any interfaces and methods to the generated Servlet, and then click on Finish. This will generate a stub for the Servlet, which you can fill with your code. The application client project will already have an application client class that you can enter your client code into. 12. To create a web service, right-click on the Web project, and select New | Other | Web Services | Web Service. This will bring up the dialog box shown in the following screenshot:
13. You can follow the instructions in the dialog to create a new web service. [ 304 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 11
The deployment plans can be edited by using the deployment plan editors, and you can click on the Source tab if you want to manually edit the XML file. Thus, we have seen how we can develop common Java EE artifacts in the Geronimo Eclipse Plugin. Support for the development of Java EE artifacts is implemented by WTP, and the steps can be found in greater detail in the WTP documentation.
Deploying and running or debugging the application in Geronimo
You can deploy the applications that you develop into the application server from the Eclipse environment by using the Geronimo Eclipse Plugin. You can right-click on the server instance shown in the Servers tab, and then select, add, or remove projects. This will bring up the Add and Remove Projects dialog box. The Available projects section will list the projects that are available in your workspace. You can select the one that you want to deploy on the server, and then click on Add. This will move the selected project to the Configured projects list. This is shown in the next screenshot:
[ 305 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Eclipse Plugin
You can click on the Finish button to deploy and start the application. You can also launch the Administration Console, in case you want to view or create server-scoped resources, or perform other administrative tasks, by right-clicking on the server and selecting Launch Administrative Console in the pop-up menu that is displayed. You can run the application by right-clicking on the application and selecting Run As | Run on Server from the pop-up menu that is displayed. You can debug the application by right-clicking on the application and selecting Debug As | Debug on Server from the pop-up menu that is displayed. If your server has already started, then a dialog box will be displayed, asking you for permission to switch to debug mode, which will require a server restart. Once you click on OK, the server and your application will be restarted in debug mode, and the application will stop during its execution at any breakpoints that you have defined.
Summary
In this chapter, we saw how the Geronimo Eclipse Plugin integrates Apache Geronimo with the Eclipse Web Tools Platform to provide a powerful environment for rapid application development. We also saw how we can develop, deploy, run, and debug Java EE 5 applications by using Eclipse WTP and the Geronimo Eclipse Plugin. In the next chapter, we will look at the clustering and load balancing features provided by Apache Geronimo for high availability and scalability.
[ 306 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Clustering A cluster is a group of linked servers working closely together to provide enterprise services—Servlets and EJBs—as if it were a single server. Clusters can be used for various reasons such as high-availability, load balancing, and so on. Configuring multiple servers to form a cluster is referred to as Clustering. These servers, referred to as nodes in the cluster, could be running on the same system or separate systems. Typically, the nodes exchange messages to synchronize data, such that any node can process the requests in a distributed application. Geronimo provides a rich set of features for creating multiple servers from the same installation (referred to as a vertical cluster), easy application management across multiple server installations on multiple systems (referred to as a horizontal cluster), and session replication between nodes in the cluster. In this chapter, we will examine the various features provided by Geronimo for the clustering of web applications and configure an Apache web server to achieve load balancing and high availability. You will learn about: •
Clustering support in Geronimo
•
Getting Geronimo server and your application ready for clustered deployment
•
Load balancing your clustered application by using Apache web server
•
Running multiple server instances from a single Geronimo installation
•
Farming
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Clustering
WADI
Geronimo supports the clustering of web applications by using WADI, Application Distribution Infrastructure. When a clustered web application is deployed in Geronimo, the deployer adds dependencies on two configurations: •
•
org.apache.geronimo.configs/clustering//car: This configuration
contains runtime dependencies that the clustered application must have. This configuration also has a Node GBean that defines a unique node name with which the Geronimo server instance will be identified in the cluster. Use the clusterNodeName property in var/config/config-substitutions. properties to reconfigure the node name of your Geronimo server instance. org.apache.geronimo.configs/wadi-clustering//car: This configuration
contains WADI-related GBeans used to configure the behaviour of clustered applications and the WADI group communication service shared by all of the clustered applications to communicate with each other.
The number of replicas to be maintained across the cluster for a session is configured as 2 by the DefaultBackingStrategyFactory GBean. To reconfigure the number of replicas, use the ReplicaCount property in var/config/config-substitutions.properties. The name for the cluster and endpoint URI are configured by the DefaultDispatcherHolder GBean. To reconfigure these, use the ClusterName and EndPointURI properties in var/config/config-substitutions.properties. WADI uses multicast for dynamic discovery of nodes in the cluster. So the server instances that want to use WADI for session replication must be running on the same subnet that supports multicast. Each node has a group communication component containing a Dispatcher and ServiceSpace wrapped in a TribesDispatcherHolder GBean and Cluster wrapped in a BasicWADICluster GBean. The group communication components can see each other and dispatch messages between them. Geronimo uses the WADI integration of Tribes for group communication. For more details on this, you can visit the Apache WADI project hosted at http://incubator.apache.org/wadi/ and Apache Tribes web page at http://tomcat.apache.org/tomcat-6.0-doc/tribes/introduction.html.
Updating deployment descriptor and deployment plan
In the Java EE deployment descriptor web.xml for your web application, you must mark the application as distributable by adding the optional element. The following shows the deployment descriptor for the Helloworld Cluster sample: [ 308 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 12
Helloworld Cluster Web Sample
HelloworldServlet sample.HelloworldServlet
HelloworldServlet /servlet/HelloworldServlet
hello.html
The Geronimo-specific deployment plan geronimo-web.xml must define the element for a clustered application to be deployed in a Geronimo Tomcat distribution. For a clustered application to be deployed in a Geronimo Jetty distribution, use the element. The following is the deployment plan of the helloworld-cluster sample from geronimo-web.xml:
packt-samples helloworld-cluster 1.0 war
/helloworld-cluster
[ 309 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Clustering
The org.apache.geronimo.configs/tomcat6-clustering-builder-wadi//car configuration must be running in order to deploy your clustered application. Otherwise, the element will not be recognized, and the deployment will fail. This configuration contains the TomcatClusteringBuilder GBean that adds the necessary dependencies on org.apache.geronimo.configs/ tomcat6-clustering-wadi//car for clustering support. Starting your clustered application will automatically start the WADI-related configurations.
Load balancing with Apache web server Apache web server, with its mod_jk plugin, can be used to load balance clustered applications deployed in Geronimo, by using the AJP Network connectors. In this section, we will see how to configure the Apache web server for load balancing and high availability.
Installing the Apache web server
The Apache web server can be downloaded from the website http://httpd. apache.org/. We have used version 2.2.11 on Windows XP to run our sample applications. You may use any 2.2.x or 2.0.x version of Apache web server. Download the binary for your operating system, and install the Apache web server. We will refer to this installation directory as .
Web app in Geronimo served through Apache web server
We have provided a simple web application, helloworld-cluster, with one static page and one servlet, to demonstrate how a web application running in Geronimo can be served using Apache web server. The HelloWorldServlet stores a counter in the HTTP session and increments the counter with each request received from the same browser session. We will first demonstrate serving this application through the Apache web server and then move on to clustering this application. Deploy the application by using the Deploy New portlet. The application is available in Geronimo at the link http://localhost:8080/helloworld-cluster/. We will now configure access to this application through Apache Web Server.
[ 310 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 12
Apache HTTP portlet
The Apache HTTP portlet in the Administration Console walks you through the process of configuring access to Geronimo through the Apache HTTP server by using mod_jk. The tool will generate the necessary configuration information based on the inputs provided by you in a step-by-step process. ���������������������������� After completing the steps, you will have the configuration text to use with workers.properties and httpd.conf. Follow ����������������������� the steps below: 1. Launch the Apache HTTP portlet by clicking on the Apache HTTP link under Server in the Console Navigation pane. The portlet screen is shown next:
2. Click on Get Started to go to the Basic Configuration screen, as shown below:
[ 311 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Clustering
3. Select the Operating System, enter the Path to workers.properties and the mod_jk log file location. Click on Next to go to the Web App Selection screen, as shown below:
4. For all of the web applications that you want to be accessible through the Apache web server, select the checkbox under the Through Apache column. If you want the Apache web server to serve the static content for an application, then select the checkbox under the Static Content column. In Dynamic Paths, enter the URL paths that should be passed on to Geronimo if the static content is served by the Apache web server. Click on Finish to see the screen with the configuration results, as shown next:
[ 312 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 12
This screen provides step-by-step instructions on configuring the Apache web server with the mod_jk plugin. Let us go over each of the steps: 1. In Step 1: Configure Geronimo for AJP, if there is an AJP connector configured already, you do not need to do anything. Otherwise, you will need to create an AJP connector. See Chapter 10, Administration, for details of how to do this. The AJP host and port will be used in Step3. 2. In Step 2: Install mod_jk, you will need to download and install the mod_jk plugin. The mod_jk plugin can be downloaded from the Apache Tomcat website, at http://tomcat.apache.org/download-connectors. cgi. You may either download the source and build the plugin yourself or download the binaries from http://www.apache.org/dist/tomcat/tomcatconnectors/jk/binaries/. Download the binary version relevant to your Operating System and your version of Apache web server, and save it to the /modules directory. Add the following lines of code to the httpd.conf file, which is located under the /conf directory: LoadModule jk_module modules/mod_jk.so
[ 313 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Clustering
Make sure that the name under which the mod_jk module file is saved under the modules directory appears in the LoadModule directive.
3. In Step 3: Create a workers.properties file, you create the workers. properties file. The configuration generated for workers.properties is as follows: worker.list=geronimo_ajp13 worker.geronimo_ajp13.port=8009 worker.geronimo_ajp13.host=localhost worker.geronimo_ajp13.type=ajp13
The complete path of the file will be used in the JkWorkersFile directive, as we will see in the next step. 4. In Step 4: Apache Configuration, you add additional configuration to the httpd.conf file. The configuration generated for httpd.conf is as follows:
The JkWorkersFile directive loads the workers defined in workers.properties. The JkLogFile directive configures the logfile for mod_jk module. The JkMount directive specifies the path and the worker to which the requests will be routed. Note that the worker geronimo_ajp13 is defined in workers.properties. [ 314 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 12
5. In Step 5: Restart Apache, you restart the Apache web server so that the configuration changes take effect.
Accessing the sample app through Apache web server
We have now configured access to the helloworld-cluster web application through Apache web server by using the mod_jk module and AJP connector provided by Geronimo. Access the application at http://localhost/helloworldcluster/. Enter a name in the form displayed, and click on getGreeting. The next page displays a greeting message along with the request information and the counter value from the session. Notice that the counter value displayed for the first access of the HelloWorldServlet is 1 and the new session value is true. Now access the application at http://localhost:8080/helloworld-cluster/ in the same browser window. Enter a name in the form displayed, and click on getGreeting. Notice that the counter value displayed on the next page is 2 and the new session value is false. The server.name indicates the server instance serving the request. Notice that the server.name value is default. This means the same application is served at both the URLs and the requests are forwarded by Apache web server to Geronimo. We will now see how this application can be clustered using Geronimo.
Running multiple server instances from a single installation Geronimo provides an easy way of creating and running multiple server instances from a single Geronimo installation. All you need to do is copy a few directories and set a few system properties, and you will have a new server instance with all of the configurations in the default instance. We will now create another instance of the Geronimo server in which we have deployed the helloworld-cluster sample application. This new instance will run in a different JVM on a different set of server ports. The two server instances replicate sessions between them such that the instance that is serving the request during a session is transparent to the user. To create a new server instance, follow the steps below:
1. Choose a name for your new server instance (for example, inst2) and create a directory with that name under the directory. We will refer to the instance name as .
[ 315 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Clustering
2. Make sure that the server is not running, and copy the contents of the /var directory, along with all of its subdirectories, to the //var directory. We will refer to the / directory as . In our example, copy to the /inst2/var directory, and the will be /inst2. 3. Open the /var/config/config-substitutions. properties file, and change the following properties: °
°
PortOffset: Change PortOffset from 0 to any integer, such that none of the server ports are in conflict. In our example, we use 10 for the PortOffset. clusterNodeName: Use this property to set a name for the
cluster node.
You can now start the new server instance by setting the system property org.apache.geronimo.server.name to the name of the server instance. You can use the JAVA_OPTS environment variable to set the system property. To start the server instance inst2, use the following commands, in a Windows environment: set JAVA_OPTS=-Dorg.apache.geronimo.server.name=inst2 /bin/geronimo run
This will start the server instance inst2. The following image shows the output in the command window at server startup:
[ 316 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 12
Notice that all of the server ports are offset by the PortOffset value of 10. The Administration Console for this server instance is available at the URL http://localhost:8090/console. With the exception of the var directory, this server instance will share the lib, repository, and other directories with the default server instance. The configurations and clustered web applications deployed in the default server will all be available on this new server instance too. At this stage, the helloworld-cluster application is available in the server instance inst2 at the URL http://localhost:8090/helloworld-cluster/. Access the application at http://localhost:8090/helloworld-cluster/ in the same browser window from which you accessed http://localhost/helloworld-cluster/. Enter a name in the form displayed, and then click on getGreeting. Notice that the counter value displayed on the next page is one more than the previous value, and the new session value is false. Even though the request is served by the application running on the new server instance inst2, as indicated by the server.name value, a new session is not created because the session state has been replicated from the default instance to inst2. However, the Apache web server is configured to forward requests only to default instances.
Clustered Helloworld-cluster application
We will now look at the configuration needed so that the two instances of the helloworld-cluster application available at http://localhost:8080/ helloworld-cluster/ and http://localhost:8090/helloworld-cluster/ are served as one logical application, by using Apache web server, the mod_jk module, and AJP connectors in Geronimo.
Updating workers.properties
To use the server instance inst2 with mod_jk, we will need to create another worker similar to geronimo_ajp13 in workers.properties. This second worker will point to the AJP connector in inst2. The configuration is as given below: worker.list=geronimo_inst2_ajp13 worker.geronimo_inst2_ajp13.port=8019 worker.geronimo_inst2_ajp13.host=localhost worker.geronimo_inst2_ajp13.type=ajp13
Add this configuration to workers.properties.
[ 317 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Clustering
The two workers geronimo_ajp13 and geronimo_inst2_ajp13 are of type ajp13. Now create another worker of type lb to balance the load between geronimo_ajp13 and geronimo_inst2_ajp13, as given below: worker.list=loadbalancer worker.loadbalancer.type=lb worker.loadbalancer.balance_workers=geronimo_ajp13,geronimo_inst2_ ajp13
You can use the lbfactor property to specify the how the load should be distributed between the workers. The load balancing factor is compared with other workers that comprise the load balancer. For example, if one worker has lb_factor twice as high as compared to the other worker, then it will receive twice as many requests. The configuration is given below: worker.geronimo_ajp13.lbfactor=2 worker.geronimo_inst2_ajp13.lbfactor=1
Here, geronimo_ajp13, that is, the default instance, will receive twice the number of requests of geronimo_inst2_ajp13, that is, instance inst2. You can also enable sticky sessions by setting the sticky_session property of loadbalancer to True. Enabling a sticky session ties a user session to a particular server instance such that subsequent requests are routed to the same instance, thus eliminating the need for session replication. If the server instance serving the request goes down, then any data stored in the session will be lost. The configuration for enabling sticky session is given below: worker.loadbalancer.sticky_session=True
See http://tomcat.apache.org/connectors-doc/reference/workers.html for complete configuration options for workers.properties. Now update the JkMount directive for /helloworld-cluster/* in httpd.conf to use the loadbalancer worker instead of geronimo_apj13. The configuration to do this is given below: JkMount /helloworld-cluster/* loadbalancer
Restart the Apache web server so that the configuration changes take effect. The helloworld-clustered application is now clustered with two nodes. Access the application at http://localhost/helloworld-cluster/. Enter a name, and click on getGreeting. The application screen is shown in the following screenshot.
[ 318 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 12
In this screen, notice the server.name value , which can be used to identify the Geronimo server instance that served the request, and stop that server instance. Now refresh or reload the page in the browser to display a screen similar to the one shown in the following screenshot:
[ 319 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Clustering
Notice that the request is now served by the other running server instance, and the counter value is incremented, indicating that the session state has been replicated to the second server instance.
Farming
By creating a new server instance by using the multiple instances feature provided by Geronimo, the new instance will have available all of the applications and configurations deployed on the default instance available and with the same runtime state. Any new application or configuration or plugin deployed in one instance will not automatically be added to the other instances. If the newly-deployed configuration adds any content to config.xml, config-substitutions.properties, and so on, then the content will not be added to the corresponding files in the other instances. If you are using multiple installations of Geronimo without the Farming feature, then you will need to deploy your clustered application on each server installation. Starting and stopping the application also needs to be done for each server installation. The Farming feature provided by Geronimo enables you to deploy an application to a cluster of Geronimo servers with a single deployment step. Once deployed to a cluster, this application can then be transparently started, stopped, or undeployed across all of the cluster members. In this section, we will look at the configuration needed on the cluster members in order to enable farming and deployment of applications in the cluster.
Cluster member configuration
Each cluster member should be given a unique name. Also, the remote deployer URL for each cluster member needs to be configured correctly. In order to do so, update the clusterNodeName and RemoteDeployHostname properties in the var/config/config-substitutions.properties file under each server instance. In the default server instance, for each additional cluster member, local or remote, add a BasicNodeInfo GBean to the farming configuration org.apache.geronimo. configs/farming/2.1.4/car in config.xml, in order to configure the connection to the cluster member using JMX. The GBean XML definition is given below:
NODE2
[ 320 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 12
system manager rmi node2hostName 1109 JMXConnector false
Make sure that the properties under extendedJMXConnectorInfo reflect the correct values required to connect to the Geronimo server instances.
Farm deployment
To use farm deployment, the farming configuration org.apache.geronimo.configs/ farming/2.1.4/car must be running on all of the cluster members. This configuration contains MasterConfigurationStore and ClusterStore GBeans. If the configuration
is not started already, then you can start it by using the System Modules portlet. To deploy your application to the cluster, use the following command:
A configuration with the configuration ID as it would be derived from regular deployment of the module and/or plan to the MasterConfigurationStore on the default server. This configuration contains GBeans to start, stop, and undeploy the application or configuration across the cluster members. A configuration with a configuration ID that is derived by adding
_G_SLAVE to the artifactId of the configuration ID from above to the MasterConfigurationStore in the default server and to the ClusterStore
in each of the cluster members.
[ 321 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Clustering
To start the application across all cluster members, use the following command: \bin\deploy.bat start
To stop the application across all cluster members, use the following command: \bin\deploy.bat stop
To undeploy the application across all cluster members, use the following command: \bin\deploy.bat undeploy
Here, the configuration ID is the ID derived in the first step above.
Running a sample application with Farm deployment
For this sample, we will use the helloworld-cluster sample with the farming-geronimo-web.xml deployment plan. We will use two separate installations of Geronimo server. Follow the steps below to run the sample application: 1. Extract the Geronimo Tomcat 2.1.4 distribution to a directory of your choice. We will refer to this directory as . 2. To create a second installation of Geronimo, extract the Geronimo Tomcat 2.1.4 distribution to a different directory of your choice. We will refer to this directory as . 3. Update the /var/config/config-substitutions. properties to change the PortOffset to 10, and the clusterNodeName to NODE2. 4. Add the BasicNodeInfo GBean��������������������������� definition given above to /var/config/config.xml under apache.geronimo. configs/farming/2.1.4/car. Make sure that the host property value is localhost. 5. Start the servers for both of installations. 6. Start apache.geronimo.configs/farming/2.1.4/car configuration in both of the instances through the System Modules portlet in the respective Administration Consoles at http://localhost:8080/console and http://localhost:8090/console.
[ 322 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 12
7. Deploy the helloworld-cluster application with the farming-geronimoweb.xml plan, by file using the command below: \bin\deploy distribute –-targets "org.apache. geronimo.configs/farming/2.1.4/car?ServiceModule=org.apache. geronimo.configs/farming/2.1.4/car,j2eeType=ConfigurationStore,na me=MasterConfigurationStore" helloworld-cluster-1.0.war farminggeronimo-web.xml
Note that this command will deploy a virtual configuration packt-samples/ helloworld-farming/1.0/war to the MasterConfigurationStore in the server at . This configuration contains GBeans to stop, start, and undeploy together the actual application deployed to the ClusterStore with configuration ID packt-samples/helloworld-farming_G_SLAVE/1.0/war in the servers at and . 8. Start the application deployed in all of the instances at once by using the following command: \bin\deploy start "packt-samples/helloworldfarming/1.0/war"
Now the application is available at URLs http://localhost:8080/helloworld-farming/ on the first server and http://localhost:8090/helloworld-farming/ on the second server. 9. Add the following line to httpd.conf, and restart the Apache web server: JkMount /helloworld-farming/* loadbalancer
The sample application is now available through the Apache web server at the URL http://localhost/helloworld-farming/. Access the application, enter a name, and click on getGreeting. The next page will display a greeting message along with the details of the request received in the Geronimo server. The org.apache. geronimo.server.home value indicates the server instance serving the request. Refresh or reload the page a few times, and notice that the application is load balanced along with session replication between the two server instances.
Summary
We have discussed vertical clustering using the multiple instances feature, horizontal clustering, and easy application management by using the farming support provided by Geronimo. We have also configured session replication by using WADI, and load balancing by using the Apache web server, mod_jk module, and AJP connectors. We have demonstrated the same by using the helloworld-cluster web application sample. In the next chapter, we will discuss the support provided by Geronimo for logging. You will learn to configure application logging using the various logging frameworks provided by Geronimo. [ 323 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Logging The ability to log important events or errors for problem diagnosis and then checking of application execution is very important. The ability to log certain statements selectively while others are not logged, depending on the context in which the application is running, is also important. An application that is deployed in Apache Geronimo can use any custom logging mechanism to log its messages. However, Apache Geronimo uses log4j and slf4j for logging server log messages. Applications deployed in Geronimo can also leverage the functionality of these logging frameworks. In this chapter, we will see how an application developer can configure logging for his application in Apache Geronimo, by using some common logging frameworks. The frameworks that we will be covering are: • • •
Apache log4j Java logging API slf4j logging adapter
We will start by briefly looking at each of the logging frameworks mentioned above, and will then go into how the server logs events and errors and where it logs them to. After examining them, we will look into the different ways in which we can configure application logging. •
Apache log4j: Log4j is an open source logging framework that is developed by the Apache Software Foundation. It provides a set of loggers, appenders, and layouts, to control which messages should be logged at runtime, where they should be logged to, and in what format they should be logged. The loggers are organized in a tree hierarchy, starting with the root logger at the top of the hierarchy. All loggers except the root logger are named entities and can be retrieved by their names. The root logger can be accessed by using the Logger.getRootLogger() API, while all other loggers can be accessed by using the Logger.getLogger() API. The names of the loggers follow the rule that the name of the parent logger followed by a '.' is a prefix to the child logger's name. For example, if com.logger.test is the name of a logger, then its direct ancestor is com.logger, and the prior ancestor is com.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Logging
Each of the loggers may be assigned levels. The set of possible levels in an ascending order are—TRACE, DEBUG, INFO, WARN, ERROR, and FATAL. If a logger is not assigned a level, then it inherits its level from its closest ancestor. A log statement makes a logging request to the log4j subsystem. This request is enabled only if its logging level is higher than or equal to its logger's level. If it is lower than the log, then the message is not output through the configured appenders. Log4j allows logs to be output to multiple destinations. This is done via different appenders. Currently there are appenders for the console, files, GUI components, JMS destinations, NT, and Unix system event loggers and remote sockets. Log4j is one of the most widely-used logging frameworks for Java applications, especially ones running on application servers. It also provides more features than the other logging framework that we are about to see, that is, the Java Logging API. •
Java Logging API: The Java Logging API, also called JUL, from the
java.util.logging package name of the framework, is another logging
framework that is distributed with J2SE from version 1.4 onwards. It also provides a hierarchy of loggers such as log4j, and the inheritance of properties by child loggers from parents just like log4j. It provides handlers for handling output, and formatters for configuring the way that the output is displayed. It provides a subset of the functionality that log4j provides, but the advantage is that it is bundled with the JRE, and so does not require the application to include third-party JARS as log4j does.
•
SLF4J: The Simple Logging Facade for Java or SLF4J is an abstraction or facade over various logging systems. It allows a developer to plug in the desired logging framework at deployment time. It also supports the bridging of legacy API calls through the slf4j API, and to the underlying logging implementation. Versions of Apache Geronimo prior to 2.0 used Apache Commons logging as the facade or wrapper. However, commons logging uses runtime binding and a dynamic discovery mechanism, which came to be the source of quite a few bugs. Hence, Apache Geronimo migrated to slf4j, which allows the developer to plug in the logging framework during deployment, thereby eliminating the need for runtime binding.
Configuring Apache Geronimo logging
Apache Geronimo uses slf4j and log4j for logging. The log4j configuration files can be found in the /var/log directory. There are three configuration files that you will find in this directory, namely:
[ 326 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 13
•
client-log4j.properties
•
deployer-log4j.properties
•
server-log4j.properties
Just as they are named, these files configure log4j logging for the client container (Java EE application client), deployer system, and the server. You will also find the corresponding log files—client.log, deployer.log, and server.log. The properties files, listed above, contain the configuration of the various appenders, loggers, and layouts for the server, deployer, and client. As mentioned above, log4j provides a hierarchy of loggers with a granularity ranging from the entire server to each class on the server. Let us examine one of the configuration files: the server-log4j.properties file: •
This file starts with the line log4j.rootLogger=INFO, CONSOLE, FILE. This means that the log4j root logger has a level of INFO and writes log statements to two appenders, namely, the CONSOLE appender and the FILE appender. These are the appenders that write to the console and to files respectively. The console appender and file appenders are configured to write to System.out and to /var/log/geronimo.log.
•
Below this section, there is a finer-grained configuration of loggers at class or package levels. For example, log4j.logger.openjpa.Enhance=TRACE.
•
It configures the logger for the class log4j.logger.openjpa.Enhance to the TRACE level. Note that all of the classes that do not have a log level defined will take on the log level of their parents. This applies recursively until we reach the root logger and inherit its log level (INFO in this case).
Configuring application logging
We will be illustrating how applications can log messages in Geronimo by using two logging frameworks, namely, log4j and JUL. We will also illustrate how you can use the slf4j wrapper to log messages with the above two underlying implementations. We will be using a sample application, namely, the HelloWorld web application to illustrate this.
Using log4j
We can use log4j for logging the application log to either a separate logfile or to the geronimo.log file. We will also illustrate how the logs can be written to a separate file in the /var/log directory, by using a GBean.
[ 327 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Logging
Logging to the geronimo.log file and the command console
Logging to the geronimo.log file and the command console is the simplest way to do application logging in Geronimo. For enabling this in your application, you only need to add logging statements to your application code. The HelloWorld sample application has a servlet called HelloWorldServlet, which has the following statements for enabling logging. The servlet is shown below. package com.packtpub.hello; import java.io.*; import javax.servlet.ServletException; import javax.servlet.http.*; import org.apache.log4j.Logger; public class HelloWorldServlet extends HttpServlet { Logger logger = Logger.getLogger(HelloWorldServlet.class.getName()); protected void service(HttpServletRequest req, HttpServletResponse res) throws ServletException, IOException { res.setContentType("text/html"); PrintWriter out = res.getWriter(); out.print(""); logger.info("Printing out "); out.print("Hello World Application"); logger.info("Printing out Hello World Application"); out.print(""); logger.info("Printing out "); out.print("Hello World "); logger.info("Printing out Hello World "); out.print(""); logger.info("Printing out "); out.print(""); logger.info("Printing out "); logger.warn("Sample Warning message"); logger.error("Sample error message"); } }
Deploy the sample HelloWorld-1.0.war file, and then access http://localhost:8080/HelloWorld/. This servlet will log the following messages in the command console, as shown in the image below:
[ 328 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 13
The geronimo.log file will have the following entries: 2009-02-02 20:01:38,906 INFO [HelloWorldServlet] Printing out 2009-02-02 20:01:38,906 INFO [HelloWorldServlet] Printing out Hello World Application 2009-02-02 20:01:38,906 INFO [HelloWorldServlet] Printing out 2009-02-02 20:01:38,906 INFO [HelloWorldServlet] Printing out Hello World 2009-02-02 20:01:38,906 INFO [HelloWorldServlet] Printing out 2009-02-02 20:01:38,906 INFO [HelloWorldServlet] Printing out 2009-02-02 20:01:38,906 WARN [HelloWorldServlet] Sample Warning message 2009-02-02 20:01:38,906 ERROR [HelloWorldServlet] Sample error message Notice that only the messages with a logging level of greater than or equal to WARN are being logged to the command console, while all the INFO, ERROR, and WARN messages are logged to the geronimo.log file. This is because in server-log4j. properties the CONSOLE appender's threshold is set to the value of the system property, org.apache.geronimo.log.ConsoleLogLevel, as shown below: log4j.appender.CONSOLE.Threshold=${org.apache.geronimo.log. ConsoleLogLevel}
The value of this property is, by default, WARN. All of the INFO messages are logged to the logfile because the FILE appender has a lower threshold, of TRACE, as shown below: log4j.appender.FILE.Threshold=TRACE
Using this method, you can log messages of different severity to the console and logfile to which the server messages are logged. This is done for operator convenience, that is, only high severity log messages, such as warnings and errors, are logged to the console, and they need the operator's attention. The other messages are logged only to a file.
[ 329 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Logging
Logging to a separate log file
In case you want your application to log to a separate logfile so that there is a separation of the log messages from the server and your application, you can follow the method described next. You can also follow this method in case your application bundles a version of log4j. In both of these cases, we use the hidden-classes feature of Geronimo to hide the log4j implementation that is bundled along with the server. This causes the application class loader to load the log4j JAR that is bundled along with your application or is given as a dependency to your application. The freshly-loaded log4j classes will again cause a new logger hierarchy, starting with a new root logger, for the application that is not aware of the log4j configurations at the server level. This application-level root logger and its descendants can be configured through a log4j.properties file in the classpath of the application. We will illustrate this by using the previous application, but this time adding the hidden-classes element to the deployment plan geronimo-web.xml. Do not forget to hide the log4j.properties file in the parent class loaders that are also using the hidden-classes element. Otherwise, your log4j implementation may get configured by any other log4j.properties file that is present in your parent class loaders. This is because resources are loaded by class loaders through a parent-first policy. You can hide the resources in the parent class loaders by using the hidden-classes element.
Add the following lines to the Geronimo deployment plan of the HelloWorld sample:
org.apache.log4j log4j
The first entry is to hide the log4j classes that are packaged with Apache Geronimo, while the second entry is to hide the log4j.properties files that may be present in parent class loaders of the application. You will also need to add a dependency on the log4j JAR in the server repository, or add the log4j JAR to your application's lib directory.
[ 330 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 13
Now you will need to configure this new instance of log4j. For this, you either need to write code to programmatically configure the loggers (for example, you want to configure your application's logging levels only through your application's user interface) in order to load custom log4j configuration files, or you need to have a log4j configuration file in your application's classpath, with a name of log4j. Log4j automatically recognizes and loads files called log4j.properties or log4j.xml, and uses the entries in these files to configure itself. In the sample, we have a log4j.properties present in the classes directory, and this will be used to configure the log4j instance in case the log4j implementations used by the parent class loaders are hidden. The contents of this file are shown below: log4j.rootLogger=INFO, CONSOLE, FILE log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender log4j.appender.CONSOLE.Threshold=TRACE log4j.appender.CONSOLE.Target=System.out log4j.appender.CONSOLE.layout=org.apache.log4j.SimpleLayout log4j.appender.FILE=org.apache.log4j.RollingFileAppender log4j.appender.FILE.Threshold=TRACE log4j.appender.FILE.layout=org.apache.log4j.SimpleLayout log4j.appender.FILE.append=true log4j.appender.FILE.file=${org.apache.geronimo.server.dir} /var/log/helloworldapp.log log4j.appender.FILE.bufferedIO=false log4j.appender.FILE.maxBackupIndex=3 log4j.appender.FILE.maxFileSize=10MB
The output will be logged to the file /var/log/helloworldapp. log, as the property log4j.appender.FILE.file is configured and the value of the property org.apache.geronimo.server.dir maps to the
directory. It will also be logged to the console. Because both the appenders have the same logging threshold, the same log messages will be output to both the log file and the console. Deploy the sample application HelloWorld-SLF4J-1.0.war, and then access http://localhost:8080/HelloWorldSLF4J/. The output in this case will look as shown in the image below:
This is different from the previous output, as this time we are using a different layout, namely, org.apache.log4j.SimpleLayout for the log messages. [ 331 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Logging
Logging using the ApplicationLog4jConfigurationGBean
Geronimo provides a GBean for configuring logging. You can use this in case you want to use the log4j implementation that is loaded and used by Apache Geronimo, but want to log your output to a different file. We will discuss the steps to do this below: • You will need to add an instance of the
ApplicationLog4jConfigurationGBean to the application's Apache Geronimo-specific deployment plan. This is shown below:
ApplicationLog4jConfigurationGBean so that it makes log4j load the configuration file that is specified through the attribute log4jFile, and then use it to add additional configurations to the server implementation of log4j. You can also specify this GBean, as shown below, in case the log4j properties file is in your application's classpath.
log4j.properties
• You should now configure application-specific logging in your log4j.properties file. This GBean prevents you from overriding global logging settings, but you can configure appenders for your application-specific loggers, as shown in the example below: #Add an appender to the HelloWorld App package logger: log4j.logger.com.packtpub.hello=INFO, helloworld #Do not add the logs to geronimo.log: log4j.additivity.com.packtpub.hello=false #Configure appenders for the helloworld app loggers: log4j.appender.helloworld=org.apache.log4j. DailyRollingFileAppender log4j.appender.helloworld.File=${org.apache.geronimo.server.dir}/ var/log/HelloWorldApp.log log4j.appender.helloworld.layout=org.apache.log4j.SimpleLayout [ 332 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 13
Using the Java Logging API
The Java logging API, by default, uses the /jre/lib/logging. properties file for configuring Loggers, Handlers, and Formatters. You can change the default logging configuration for all programs using that JRE and the Java logging API, by editing this file. You can also specify two system properties to change the logging configuration for each run of the JRE. These properties are: •
java.util.logging.config.file: The value of this property should be the path of a file in the properties file format that contains the initial logging configuration.
•
java.util.logging.config.class: The value of this property should be
the fully-qualified name of the class whose constructor is responsible for reading in the initial configuration.
If you need to set these at startup for Apache Geronimo, then you can use the GERONIMO_OPTS or the JAVA_OPTS environment variable, as shown below: set GERONIMO_OPTS=-Djava.util.logging.config.file=C:\xyz\logging. properties
The default configuration configures a ConsoleHandler with a SimpleFormatter and the log level set to INFO. You can programmatically configure the Java Logging API to accept different log files. You can do this either in a custom GBean or in the code that is executed during the startup of your application, for example ServletContextListener.
Using the SLF4j logging adapter
Apache Geronimo uses slf4j over log4j for logging purposes. Geronimo ships with the following slf4j modules included in the repository: •
slf4j-api
•
slf4j-log4j12
•
jcl-over-slf4j
•
jul-to-slf4j
Getting your application to use slf4j for logging is a very simple process. We will demonstrate this by converting the application that we have been using up to now, that is, the HelloWorld application, to use slf4j for logging.
[ 333 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Logging
The first step in this is to add dependencies to the slf4j-api and slf4j-log4j12 JARs. We will then need to import the slf4j classes that we are going to use for logging in our class. These import statements are shown below: import org.slf4j.Logger; import org.slf4j.LoggerFactory;
In the next step, remove the previous import of the log4j logger and then replace the log4j API for getting the logger: Logger logger = Logger.getLogger(HelloWorldServlet.class.getName());
with the slf4j API: Logger logger = LoggerFactory.getLogger(HelloWorldServlet.class);
You will now be able to use slf4j for logging to the geronimo.log file. If you want to log to a separate file, then you can either use the hidden-classes element or the ApplicationLog4jConfigurationGBean. The log4j configurations remain the same. The only additional thing that you should remember if you are using hidden-classes is that you should also hide the slf4j implementation that is shipped with Geronimo, that is, the org.slf4j package. The converted application is provided in the samples directory, and is called HelloWorld-SLF4J. Thus, we can see that, at deployment time, we can deploy a static JAR—configured to work with either JUL or log4j—so that a developer can use JUL/slf4j, but the application can be deployed with log4j/slf4j without changing even a single line of code. This is the advantage that using a logging facade provides.
Summary
In this chapter, we have seen the various logging frameworks supported by Geronimo, namely, LOG4J, JUL, and SLF4J. We have discussed how the application server and application-specific logging can be configured using these frameworks. In the next chapter, we will introduce you to some advanced Apache Geronimo concepts and provide you with a view of the internals of Apache Geronimo.
[ 334 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Internals Apache Geronimo consists of a kernel that provides dependency management, configuration management, lifecycle management, and repository services. A GBean is a basic building block in Geronimo that wraps a service or provides a service by itself. GBeans are grouped into configurations that start and stop as a group. These configurations are themselves GBeans that use the services of other GBeans such as the repository and so on. As a result, they provide us with a hierarchy of GBeans, using services from one another in a neatly choreographed way. In this chapter, we will look at the building blocks of Geronimo that enable it to provide the services required of a Java EE 5-compliant application server. This chapter is divided into three major sections, dealing with: • • •
Services provided by Geronimo Configurations and deployment Development and deployment of GBeans
Services provided by Geronimo
We will look at some of the low-level services provided by Geronimo.
Kernel
The Kernel interface provides methods to obtain various services such as LifecycleMonitor, DependencyManager, ProxyManager, and so on. It also provides methods to query GBeans, load, start, stop, unload GBeans, set, and get GBean attributes, and invoke methods on GBeans. You can instantiate a kernel instance by using the KernelRegistry.getSingleKernel() API. We will now look at some of the APIs in the Kernel, and their uses: •
getDependencyManager(): Returns the DependencyManager kernel service. The DependencyManager uses the nomenclature of parent-child, where a child is dependent on a parent. DependencyManager is used to manage dependencies between GBeans.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Internals
•
getLifecycleMonitor(): Returns the LifecycleMonitor kernel service.
•
getNaming(): Returns the naming system used by the kernel.
•
getProxyManager(): Returns the ProxyManager kernel service. ProxyManager manages kernel proxies. All proxies include an implementation of GeronimoManagedBean.
•
loadGBean(): Loads a specific GBean into the kernel, using a specified
class loader.
•
isLoaded(): Returns true if a GBean is registered in the kernel under the specified name.
•
getGBean(): Returns the GBean registered in the kernel with the
specified name.
•
startGBean(): Starts the GBean registered in the kernel with the
•
startRecursiveGBean():Starts the GBean registered in the kernel with the specified name, along with and all of its child GBeans as registered in the DependencyManager.
•
isRunning(): Returns true if the specified GBean is running.
•
stopGBean(): Stops the GBean with the specified name.
•
unloadGBean(): Unloads the GBean with the specified name.
•
getGBeanState(): Returns the state of the GBean with the specific name.
•
getGBeanStartTime(): Returns the starting time of the GBean with the
•
getClassLoaderFor(): Returns the class loader used to register the
•
getGBeanInfo(): Returns the GBeanInfo of a specified GBean instance.
•
getGBeanData(): Returns the GBeanData of a specified GBean instance.
•
listGBeans(): Returns a list of GBean names loaded in the kernel that match a specified abstract name query.
• •
specified name.
specified name.
specified GBean.
getAttribute(): Returns the value of a specific attribute in a specified
GBean instance.
setAttribute(): Sets the value of a specific attribute in a specified
GBean instance.
[ 336 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 14
•
invoke(): Invokes a specified method on a specified GBean instance.
•
getAbstractNameFor(): Returns the abstract name for the service represented by the specified object.
•
getShortNameFor(): Returns the short name for the service represented by
•
boot(): Boots the kernel.
•
getBootTime(): Returns the boot time of the kernel.
•
registerShutdownHook(): Registers a runnable object to run at
•
unregisterShutdownHook(): Unregisters a runnable object registered earlier using the registerShutdownHook() API.
•
shutdown(): Shuts down the kernel.
•
isRunning(): Returns true if the kernel is booted.
•
getStateReason(): Returns the state message associated with a
the specified object.
kernel shutdown.
specified GBean.
ServerInfo
The ServerInfo contains information about the server, and functions to resolve pathnames. The interface definition is given below: public interface ServerInfo { public File resolve(final String filename); public File resolveServer(final String filename); public String resolvePath(final String filename); public String resolveServerPath(final String filename); public URI resolve(final URI uri); public URI resolveServer(final URI uri); public String getBaseDirectory(); public String getCurrentBaseDirectory(); public String getVersion(); public String getBuildDate(); public String getBuildTime(); public String getCopyright(); }
[ 337 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Internals
We will now look at the APIs in ServerInfo, and their uses: •
resolve(): Resolves a specified relative path name to a file relative to the server installation directory. For example, "foo" resolves to /foo.
•
resolveServer(): Resolves a specified relative path name to a file relative
to the server instance directory. For the default instance, the server instance directory is the same as the server installation directory. For an instance started by specifying the org.apache.geronimo.server.name system property, this resolves to a path under the / directory. For example, for a server instance with a name of instance2, "foo" resolves to /instance2/foo.
•
resolvePath(): Returns an absolute path relative to the server
•
resolveServerPath(): Returns an absolute path relative to the server
•
resolve(URI): Resolves the specified URI relative to the server
•
resolveServer(URI): Resolves the specified URI relative to the server
•
getBaseDirectory(): Returns the server base directory. By default, this
•
getCurrentBaseDirectory(): Returns the absolute path name of the server
•
getVersion(): Returns the server version information.
•
getBuildDate(): Returns the server build date.
•
getBuildTime(): Returns the server build time.
•
getCopyright(): Returns the server copyright information.
installation directory. instance directory.
installation directory. instance directory.
is the server installation directory. The base directory can be overridden by using the org.apache.geronimo.home.dir system property.
base directory.
You can obtain a ServerInfo object by calling the Kernel API getGBean() with ServerInfo.class as a parameter.
Configurations and deployment
In this section, we will investigate some of the classes that provide the deployment and configuration management functionality of Apache Geronimo.
[ 338 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 14
ConfigurationManager
A ConfigurationManager encapsulates the logic for dealing with configurations. Configurations have a lifecycle with three states: installed, loaded, and running. Installed means that the configuration is present in the server's repository. Loaded means that the configuration Gbean, including the configuration's ClassLoader, is running. Running means that all of the GBeans in the configuration are running. When a configuration is not loaded, only its ConfigurationData is available for inspection. It's normally not possible to inspect the GBeans in the configuration because there's no ClassLoader that could be used to load the classes needed by the instances of GBeanData in the configuration. Once the configuration has been loaded, its ClassLoader is available so that the instances of GBeanData can be loaded and inspected. But the GBean instances are not instantiated and started until the configuration is started. We will now look at some of the APIs in the ConfigurationManager interface: • •
isInstalled(): Returns true if a specified configuration is installed on
the server.
isLoaded(): Returns true if a specified configuration is loaded into
the kernel.
•
isRunning(): Returns true if a specified configuration is running.
•
getInstalled(): Returns a list of installed configurations, g����������������� iven an artifact that's not fully resolved (for example, some parts are missing), that is, any of the matching configurations in the configuration store, regardless of whether they're loaded or running.
•
getLoaded(): Returns a list of configurations, g����������������������������� iven an artifact that is not
•
getRunning(): Returns a list of configurations, g����������������������������� iven an artifact that is not
•
fully resolved (for example, some parts are missing), and check whether there are any instances loaded.
fully resolved (for example, some parts are missing), and check whether there are any instances running.
listConfigurations(): Returns a list of all of the configurations installed
on the server.
•
listStores(): Returns a list of abstract names of the configuration stores
•
getStores(): Returns an array containing all of the configuration stores
•
isConfiguration(): Returns true if a specified artifact is a configuration in
controlled by this configuration manager. known to this configuration manager. the server.
[ 339 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Internals
•
loadConfiguration(): Loads a specified configuration.
•
getConfiguration(): Returns the configuration for a given artifact ID.
•
unloadConfiguration(): Unloads a specified configuration.
•
startConfiguration(): Starts a specified configuration and the contained
GBeans. It will also start any parent configurations.
•
stopConfiguration(): Stops a specified configuration and the containing
•
restartConfiguration(): Restarts a specified configuration and the containing GBeans. It will also restart any child configurations.
•
reloadConfiguration(): Reloads a specified configuration and the containing GBeans. It will also reload any child configurations.
•
GBeans. It will also stop any child configurations.
uninstallConfiguration(): Uninstalls a specified configuration from
the server.
•
isOnline(): Returns true if the ConfigurationManager is fully functional.
•
getRepositories(): Returns a collection of repositories known to this
•
getArtifactResolver(): Returns the ArtifactResolver ������������������� configured for all of the repositories known to this ConfigurationManager.
ConfigurationManager.
Configurations are identified by their artifact IDs.
You can obtain a ConfigurationManager by calling the API ConfigurationUtil. getConfigurationManager(), with the kernel passed as a parameter.
EditableConfigurationManager
EditableConfigurationManager enables you to dynamically change the set of
GBeans included in the configuration at runtime. The interface definition is as follows: public interface EditableConfigurationManager extends ConfigurationManager { void addGBeanToConfiguration(Artifact configID, GBeanData gbean, boolean start) throws InvalidConfigException; void addGBeanToConfiguration(Artifact configID, String name, GBeanData gbean, boolean start) throws InvalidConfigException; void removeGBeanFromConfiguration(Artifact configID, AbstractName gbean) throws InvalidConfigException, GBeanNotFoundException; } [ 340 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 14
•
•
addGBeanToConfiguration: Adds a new GBean defined by GBeanData to an existing configuration identified by the configID. The start parameter determines whether the newly-added GBean should be started or not. removeGBeanFromConfiguration: Removes the GBean specified by its abstract name from the configuration identified by configID.
LocalAttributeManager
ConfigurationManager uses an AttributeManager service to manage the GBean attributes of the GBeans deployed on the server. The LocalAttributeManager is configured by two files, namely, config.xml and config-substitutions. properties, which are located under the var/config directory, in order to the enable editing of GBean attribute values. The properties defined in config-substitutions. properties can be used in composing expressions for attribute values defined in config.xml. The following is an excerpt from config.xml:
${SMTPHost} ${SMTPPort}
Here, the host attribute of the SMTPTransport GBean in the org.apache.geronimo. configs/javamail/2.1.4/car configuration are overridden by using an expression of ${SMTPHost}. The property SMTPHost is defined in config-substitutions. properties as follows: SMTPHost=localhost
Therefore, the attribute value will evaluate to localhost. If the SMTPHost is used in multiple places in config.xml, then config-substitutions.properties provides an easy way to effect a change by making a change in only one place.
ArtifactResolver
ConfigurationManager uses the ArtifactResolver service for artifact resolution while loading configurations. The ArtifactResolver GBean is configured by the artifact_aliases.properties file, which is located under the var/config
directory, in order to support the substitution of one artifact for another at runtime. This file contains entries in the format oldartifactid=newartifactId. The following is an excerpt from artifact_aliases.properties: org.apache.geronimo.plugins/mconsole-ds//car=org.apache.geronimo. plugins/mconsole-ds/2.1.4/car org.apache.geronimo.framework/geronimo-gbean-deployer/2.1/car=org. apache.geronimo.framework/geronimo-gbean-deployer/2.1.4/car [ 341 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Internals
Here, all references to org.apache.geronimo.plugins/mconsole-ds//car, where the version is not specified, will be resolved to org.apache.geronimo.plugins/ mconsole-ds/2.1.4/car, and any reference to org.apache.geronimo.framework/ geronimo-gbean-deployer/2.1/car will be resolved to org.apache.geronimo. framework/geronimo-gbean-deployer/2.1.4/car. The artifact-aliases. properties file comes in handy when you have deployed configurations pointing to an explicit version of a JAR that you will want to upgrade to, without having to redeploy the configuration. Although overwriting the older JAR with a newer version could be a crude way of resolving the problem, artifact aliasing offers a cleaner way of achieving the same thing. Note that in the entries, the version number can be omitted from the left-hand side but not from the right-hand side.
Developing a new GBean
In this section, we will look at creating a new GBean and deploying the GBean to the server. Remember that a GBean is the basic unit in Geronimo that may provide a service or is used to wrap services deployed in the kernel. We will now develop a GBean, and in the process, we will look at various aspects of the GBean, such as the attributes, references, operations, constructor, interfaces, lifecycle management, dependencies, and so on. A GBean Java class typically implements a service interface and exposes the operations from the service interface or provides lifecycle operations such as start or stop to initialize and shutdown the service. A GBean can use lifecycle management by implementing the GBeanLifecycle interface. The GBean is configured by attributes and references to other GBeans. Irrespective of what the Java class defines, the GBean is only identified by the structure defined by the GBean's metadata GBeanInfo. The Java class defining a GBean should make the GBeanInfo available through a static method getGBeanInfo(). The following is a typical structure of a Java class that defines a GBean: public class MySampleGBean implements MySampleInterface, GBeanLifecycle { ... public MySampleGBean(...) { .... } ... /* Lifecycle methods */ public void doStart() throws Exception { ... } public void doStop() throws Exception { [ 342 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 14 ... } public void doFail() { ... } public static final GBeanInfo GBEAN_INFO; static { GBeanInfoBuilder infoFactory = GBeanInfoBuilder.createStatic ("GBean", MySampleGBean.class); // Initialize the GBean structure here ... GBEAN_INFO = infoFactory.getBeanInfo(); } public static GBeanInfo getGBeanInfo() { return GBEAN_INFO; } }
The static block at the bottom of the listing is used to initialize the GBeanInfo for the GBean. We use the GBeanInfoBuilder helper class to create the GBeanInfo.
GBean attributes
Attributes are used to configure the GBean. Each attribute must have a name and a type. Optionally, an attribute can be persistent, which means that the attribute's value will be saved and applied each time the GBean is loaded. Moreover, an attribute can be manageable, which means that the attribute's value can be overridden by using config.xml. Except for the four "magic" attributes (as we will see next), usually all attributes are persistent, and most attributes are manageable. The GBeanInfoBuilder. addAttribute() method can be used to add information about GBean attributes to the GBeanInfo. This method takes four parameters, as given below: •
name—String value specifying the name of the attribute.
•
type—Class specifying the type of the attribute.
•
Persistent—Optional Boolean value specifying whether the attribute
•
is persistent.
Manageable—Optional Boolean value specifying whether the attribute is manageable.
The following is an excerpt from the MySampleGBean class. infoFactory.addAttribute("name", String.class, true, true); infoFactory.addAttribute("name2", String.class, true, false); [ 343 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Internals
This code defines a persistent and manageable attribute with name name of type String and a persistent but not manageable attribute with name name2 of type String. A GBean can have zero or more attributes defined for it.
Magic attributes
Geronimo provides four special attributes that cannot be configured by a user. These attributes, referred to as magic attributes, must be designated as not persistent and non-manageable. The attribute details are as follows: •
kernel: This attribute is of type Kernel. The value for this attribute is the
•
objectName: This attribute is of type String. The value of this attribute is the
•
abstractName: This attribute is of type AbstractName. The value of this
•
classLoader: This attribute is of type ClassLoader. The value of this
Geronimo kernel in which the GBean is running.
JMX ObjectName that can be used to refer to this GBean component.
attribute is the unique name identifying this GBean instance.
attribute is the class loader that is used for the current configuration.
The following is an excerpt from the MySampleGBean class: infoFactory.addAttribute("kernel", Kernel.class, false); infoFactory.addAttribute("objectName", String.class, false); infoFactory.addAttribute("abstractName", AbstractName.class, false); infoFactory.addAttribute("classLoader", ClassLoader.class, false);
This code defines the four magic attributes for the MySampleGBean class. The kernel attribute is used whenever you want to invoke certain kernel method implementations in your GBean. Geronimo will inject an instance of the currently-used kernel into that attribute. Similarly, usage of the abstractName and objectName attributes ensures that these are available to the GBean. The classLoader attribute is used when we need to gain access to the configuration's class loader.
GBean references
A GBean can reference other GBeans running in the kernel. A GBean reference has a name and a type. A reference can be either single valued or multiple valued. In the case of multiple valued references, the reference will be made to multiple GBeans of the same type. The GBeanInfoBuilder.addReference() method can be used to add GBean references to GBeanInfo. The parameters to this method are as follows: [ 344 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 14
•
name—A string value specifying the name of the reference.
•
type—A class representing the type of the reference. In the case of
•
namingType—A string representing the J2EE type of the reference.
multiple valued references, the corresponding argument in the constructor or getter/setter methods will have the type Collection, and the type of the element in the collection is specified by this type parameter.
The following is an excerpt from the MySampleGBean class: infoFactory.addReference("ServerInfo", ServerInfo.class);
This code defines a single valued GBean reference with name ServerInfo of type ServerInfo. A GBean can have zero or more references defined for it.
GBean operations
A GBean can make zero or more service operations available. The GBeanInfoBuilder.addOperation() method can be used to add GBean operations to GBeanInfo. The parameters for this method are as follows: •
name—A string value specifying the name of the operation.
•
parameterTypes—An optional array of class objects specifying the parameter types of the operation.
•
returnType—An optional string value specifying the return type of the operation.
The following is an excerpt from the MySampleGBean class: infoFactory.addOperation("myMethod1", "java.lang.String");
This code defines a GBean operation with the name myMethod1, with no arguments, and the return type String.
GBean constructor
A GBean can have a constructor configured by using the GBeanInfoBuilder. setConstructor() method. The parameter to this method is as follows: •
parameterNames—An array of strings containing the names of attributes����� ��������������� and
references that form the parameters of the constructor.
[ 345 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Internals
The following is an excerpt from the MySampleGBean class: infoFactory.setConstructor(new String[] {"kernel", "objectName", "abstractName", "classLoader", "name"});
This code defines a GBean constructor with five parameters, which are all GBean attributes. If no GBean constructor is defined, then the Java class must have a public no-argument constructor defined.
GBean interface
A GBean can have zero or more service interfaces defined by using the GBeanInfoBuilder.addInterface() method. The parameters to this method are as follows: • • •
intf—The Java interface that should be added as the GBean interface. persistentAttributes—An optional array of strings specifying
persistent attributes.
manageableAttributes—An optional array of strings specifying
manageable attributes.
The following is an excerpt from MySampleGBean: infoFactory.addInterface(MySampleInterface.class);
This code adds MySampleInterface as a GBean interface in MySampleGBean. Adding an interface as the GBean interface allows the querying of the kernel for GBeans using the interface.
GBeanLifecycle
A GBean can use lifecycle management support by implementing the GBeanLifecycle interface. The methods in this interface are as follows: •
doStart()—This method is called when the GBean is started. Any module
dependencies, GBean dependencies, and any GBeans in the references will have been started already.
•
doStop()—This method is called when the GBean is stopped.
•
doFail()—This method is called when the GBean can not be started due to an exception in doStart().
[ 346 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 14
Sample GBean MySampleGBean Create a Maven project by using the following command:
This will create a directory gbean-sample with pom.xml. Change the pom.xml as given below, to add dependencies such as geronimo-kernel and geronimo-system JARs, as our GBean uses classes from these Geronimo modules:
4.0.0 packt-samples gbean-sample jar 1.0 gbean-sample http://maven.apache.org
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Internals
Run the following command to create Eclipse project artifacts: mvn –Peclipse eclipse:eclipse
Import the project into an Eclipse workspace by using the option File | Import | Import Existing Projects into Workspace. Create a Java interface named packtsamples.MySampleInterface. This interface definition is given below: package packtsamples; public interface MySampleInterface { String myMethod1(); }
Create a Java class named packtsamples.MySampleGBean. The class definition is given below: package packtsamples; ... public class MySampleGBean implements MySampleInterface, GBeanLifecycle { private Kernel kernel; private String objectName; private AbstractName abstractName; private ClassLoader classLoader; private String name; private String name2; private ServerInfo serverInfo; public MySampleGBean(Kernel kernel, String objectName, AbstractName abstractName, ClassLoader classLoader, String name) { this.kernel = kernel; this.objectName = objectName; this.abstractName = abstractName; this.classLoader = classLoader; this.name = name; System.out.println("kernel = "+kernel); System.out.println("objectName = "+objectName); System.out.println("abstractName = "+abstractName); System.out.println("classLoader = "+classLoader); System.out.println("name = "+name); } public void setServerInfo(ServerInfo serverInfo) { this.serverInfo = serverInfo; System.out.println("serverInfo = "+serverInfo); } [ 348 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 14 public String myMethod1() { StringBuffer out = new StringBuffer(this.getClass() .getSimpleName()+"["+name+"].myMethod1()\n"); out.append("server version = "+serverInfo.getVersion()+"\n"); out.append("server build date = "+serverInfo.getBuildDate() +"\n"); out.append("server build time = "+serverInfo.getBuildTime() +"\n"); out.append("server copyright = "+serverInfo.getCopyright()+"\n"); out.append("server base directory = "+serverInfo.getBaseDirectory()+"\n"); out.append("server current base directory = "+serverInfo.getCurrentBaseDirectory()); System.out.println(out.toString()); return out.toString(); } public void setName(String name) { this.name = name; } public void setName2(String name2) { this.name2 = name2; } public void doFail() { System.out.println(this.getClass().getSimpleName()+ "["+name+"] Failed............."); } public void doStart() throws Exception { System.out.println(this.getClass().getSimpleName()+ "["+name+"] Started............"); } public void doStop() throws Exception { System.out.println(this.getClass().getSimpleName()+ "["+name+"] Stopped............"); } public static final GBeanInfo GBEAN_INFO; static { GBeanInfoBuilder infoFactory = GBeanInfoBuilder.createStatic ("GBean", MySampleGBean.class); // Initialize the GBean structure here infoFactory.addAttribute("kernel", Kernel.class, false); infoFactory.addAttribute("objectName", String.class, false); infoFactory.addAttribute("abstractName", AbstractName.class, false); infoFactory.addAttribute("classLoader", ClassLoader.class, false); [ 349 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Build the module by using the following command: mvn install
This will create the module JAR file gbean-sample-1.0.jar under the target directory. This JAR contains the GBean definition class of MySampleGBean. In the next section, we will see how we can create instances of this GBean.
Deploying the GBean
The gbean-sample-1.0.jar can be packaged in a WAR file or EAR file, and the GBean declaration XML can be added to the deployment plan of those applications. We will deploy a service module with four instances of the MySampleGBean. Before deploying the service module, upload the gbean-sample-1.0.jar to the server repository by using the Repository portlet. Select the file for upload. This will populate the artifactId, version, and type fields. Enter packt-samples for the groupId, and click on Install to upload the JAR. Use the Deploy New portlet to deploy the service module with the plan file provided under the samples. The same deployment plan is given below:
packt-samples mygbean 1.0 car
[ 350 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 14 org.apache.geronimo.framework j2ee-system car
packt-samples gbean-sample jar
mysamplegbean
ServerInfo
mysamplegbean2
ServerInfo
mysamplegbean3
ServerInfo
mysamplegbean4
mysamplegbean4
ServerInfo
[ 351 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Geronimo Internals
Here we have created four instances of MySampleGBean with GBean names mysamplegbean, mysamplegbean2, mysamplegbean3, and mysamplegbean4. Notice that under the dependencies element, we have added a dependency on packtsamples/gbean-sample//jar, which contains our GBean definition. Also notice that the dependency on org.apache.geronimo.framework/j2ee-system//car contains the ServerInfo GBean that we are using as a reference. The console output upon deploying this plan is as shown in the screenshot below:
Usually, the GBeans in the module are started in the same order as they are defined in the deployment plan. When the instances of MySampleGBean are started, a message is displayed in the Geronimo console window, giving the name of the GBean. Note that even though we have not configured the magic attributes in our deployment plan, the Geronimo server has provided values for these attributes. These attribute values are displayed in the command window. Notice that even though mysamplegbean3 is defined before mysamplegbean4 in the deployment plan, mysamplegbean4 is started before mysamplegbean3. This is because of the dependency mysamplegbean3 has on mysamplegbean4, as declared in the deployment plan. [ 352 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 14
Testing the GBean with GBean web app sample In order to test the MySampleGBean, we have provided a gbean-webapp web which is application in the samples. This sample contains a GBeanServlet,���������� shown below:
public class GBeanServlet extends HttpServlet { private static final long serialVersionUID = 1L; private Kernel kernel; @Override public void init(ServletConfig config) { kernel = KernelRegistry.getSingleKernel(); } @Override protected void service(HttpServletRequest request, HttpServletResponse response) throws IOException { response.setContentType("text/plain"); PrintWriter out = response.getWriter(); out.println("GBeanServlet"); out.println("Query using interface name MySampleInterface..."); try { AbstractNameQuery query = new AbstractNameQuery (MySampleInterface.class.getName()); Set gbeanNames = kernel.listGBeans(query); out.println("number of gbeans = "+gbeanNames.size()); for(Iterator itr = gbeanNames.iterator(); itr.hasNext(); ) { out.println(itr.next()); } gbeanNames = kernel.listGBeans(query); AbstractName gbeanName = (AbstractName) gbeanNames.iterator() .next(); out.println("\nObtaining gbean instance using abstract name " +gbeanName); MySampleInterface gbean = (MySampleInterface) kernel.getGBean(gbeanName); out.println(gbean); out.println("\nInvoking gbean method via proxy object..."); out.println((String)gbean.myMethod1()); out.println("\nInvoking set attribute on gbean "+gbeanName); kernel.setAttribute(gbeanName, "name", ((String) kernel.getAttribute(gbeanName, "name")).toUpperCase()); kernel.setAttribute(gbeanName, "name2", ((String) kernel.getAttribute(gbeanName, "name2")).toUpperCase()); out.println("\nInvoking invoke on gbean "+gbeanName); out.println((String)kernel.invoke(gbeanName, "myMethod1")); [ 353 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
This servlet obtains an instance of kernel by using KernelRegistry, queries the kernel for instances of MySampleGBean, and executes operations on the GBeans. Deploy the gbean-webapp-1.0.war by using the Deploy New portlet, and access the application at http://localhost:8080/gbean-webapp/. The output from the servlet is shown in the screenshot below:
Observe the following in this output: •
The query for GBeans using the interface MySampleInterface has yielded 4 results.
•
The servlet obtains the GBean MySampleGBean by using the getGBean API and invokes myMethod1() using the GBean object. Notice that myMethod1() has retrieved the server details using ServerInfo.
[ 354 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Chapter 14
•
The servlet has invoked the setAttribute kernel API on MySampleGBean to set the name attribute to MYSAMPLEGBEAN and name2 attribute to MYSMPLGBN. �������������������������������������������������������� Notice that the following XML fragment gets added under the packt-samples/mygbean/1.0/car module element in the config.xml file, as shown below:
MYSAMPLEGBEAN
•
The attribute value change for name2 is not reflected in config.xml as name2 is not a manageable attribute.
•
The servlet then invokes the GBean operation myMethod1 on MySampleGBean. Notice that the value of name is now displayed in uppercase in the output.
Now launch the System Modules portlet and stop the configuration
packt-samples/mygbean/1.0/car. Notice the log messages displayed in the console by the doStop() lifecycle method.
Summary
In this chapter, we have taken a look at some of the important services provided by Geronimo, such as the kernel, ServerInfo, Configuration-Manager, AttributeStore, and ArtifactResolver. We have also looked at how low-level kernel services can be used to directly interact with GBeans and invoke services on GBeans. We have developed a new GBean to familiarize you with various aspects of GBeans, and demonstrated the newly-developed GBean by using a sample web application. This brings us to the end of this book on Apache Geronimo. You should now be familiar with most of the configuration aspects of the Apache Geronimo server, as well as being aware of the architecture that Geronimo is built on.
[ 355 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Deployment Plans A deployment descriptor is an XML file that describes a Java EE module. It lists the Java EE components that make up the module and defines the environment for these components. Java EE components have access to a naming service called JNDI, which is used to decouple the component from the resources and other components that it uses. The process of mapping the actual resources to the references in the application is done by means of the Java EE deployment descriptors and server-specific deployment plans. By deployment plans, we refer to the server-specific XML files that help in deployment. These files can be created by tooling or by hand. The different types of deployment descriptors, as specified in the Java EE specifications, are as follows: •
Web deployment descriptor: This file should be named web.xml, and should be present in the WEB-INF directory of your web module.
•
EJB deployment descriptor: This file should be named ejb-jar.xml, and should be present in the META-INF directory of the EJB module.
•
Application deployment descriptor: This file should be named
application.xml, and should be present in the META-INF directory
of the EAR file in which the application is packaged. •
Application Client deployment descriptor: This file should be named application-client.xml, and should be present in the META-INF directory of the application client module.
•
Resource Adapter deployment descriptor: This file should be named ra.xml, and should be present in the META-INF directory of the resource adapter module.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Deployment Plans
There are Geronimo-specific deployment plan counterparts for each of the Java EE 5 deployment descriptors. These are given below: •
Web deployment plan: This file should be named geronimo-web.xml, and should be present in the WEB-INF directory of your web module. This maps the resource references in the web.xml file to server resources.
•
EJB deployment plan: This file should be named openejb-jar.xml, and should be present in the META-INF directory of the EJB module. This maps the resource references in the ejb-jar.xml file to resources on the server.
•
Application deployment plan: This file should be named
geronimo-application.xml, and should be present in the META-INF
directory of the EAR file in which the application is packaged.
•
•
Application Client deployment plan: This file should be named
geronimo-application-client.xml, and should be present in the META-INF directory of the application client module.
Resource Adapter deployment plan: This file should be named geronimo-ra.xml, and should be present in the META-INF directory of the resource adapter module.
An external deployment plan can also be specified during deployment. In this case, the plan file can have any name, and will override any deployment plan packaged within the archives. Deployment plans are used to deploy services such as security realms into Geronimo. If the Service deployment plan is provided internally in the Java archive, it should be named geronimo-service.xml, and located under the META-INF directory. All deployment plans use some common elements, such as environment and gbean definitions. In this appendix, we will examine these common elements.
Environment
The environment element defines elements that are used to store information such as the Module ID, dependencies, and the class loader for the module. This element is used in all of the Services and application modules' deployment plans. This element is defined in the namespace http://geronimo.apache.org/xml/ns/ deployment-1.2. The schema representation is shown below:
[ 358 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Appendix A
The description of various elements under environment is as follows: •
moduleId: moduleId holds elements for the groupId, artifactId, version, and type of the module. Module IDs are normally specified with slashes between the four components, such as GroupID/ArtifactID/Version/Type. °
groupId: This ID is used to name the group containing this module. When groupId is not specified, by default,
it is considered 'default' for declaration and wildcard '*' for dependencies. °
artifactId: This ID is used to name the module in a specified group. If no articfactId is provided, it will be defaulted
to the file name of the module file. In case of dependencies, artifactId must be provided. °
version: This is used to specify the version number of the module, formatted by dot-separated numbers. If no version is provided, then it will be defaulted to a numeric timestamp generated by System.currentTimeMillis() at deploy time. In case of dependencies, the latest available version in the repository will be used.
[ 359 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Deployment Plans
°
•
type: This element defines the type of the module. The
type could be CAR, JAR, EAR, WAR, and so on. If no type is provided, then it will be defaulted appropriately by the deployer, depending upon the type of deployed module. In the case of dependencies, JAR will be used.
dependencies: The dependencies element defines all of the dependencies
of this module on other modules and repository artifacts. You can specify zero or more dependencies by using the dependency child element. Each dependency element may contain groupId, artifactId, version, type, and import elements. See moduleId above, for a description of groupId, artifactId, version, and type. °
import: The import element is a restrictive element used to
define the type of dependency. The default (when omitted) is to include the specified dependency in the class loader (as a parent or URL). If defined as "classes", it means that the classes must be included in the current module's class loader but the dependency does not need to be started. Specifying "services" means that the dependency (a module) must be started before the current module, but it is not included as a parent class loader.
•
hidden-classes: This element is used to specify a list of classes that will never be loaded from parent class loaders of this module. For example, if Log4J was listed here, the module would never see Geronimo's copy of Log4J. If the module provides its own Log4J JAR then it would use that. Otherwise, it would not be able to load Log4J at all. 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 in this element will be treated as hidden.
•
non-overridable-classes: This element is used to specify a list of classes that will only be loaded from parent class loaders of this module (never from the module's own class loader). For example, this is used to prevent a web application from redefining javax.servlet, so those classes will always be loaded from the server instead of the web application's own class-path. 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 non-overridable.
•
inverse-classloading: If this element is specified, the standard class loading delegation model is to be reversed for this module.
[ 360 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Appendix A
•
suppress-default-environment: If this element is specified, then any default environment built by a builder when deploying the plan will be suppressed. An example of where this is useful is when deploying a connector on an application client in a separate (standalone) module (not as part of a client plan). The connector builder default Environment includes some server modules that won't work on an application client, so you need to suppress the default environment and supply a complete environment including all parents for a non-application-client module that you want to run on an application client.
A typical environment element in a deployment plan looks like the block of code below:
packt-samples helloworld 1.0 war
log4j log4j 1.2.14 jar classes
org.apache.log4j
javax.servlet
Here the module will be deployed under the ID packt-samples/helloworld/1.0/ war. The module has a dependency on the log4j/log4j/1.2.14/jar repository artifact. All classes in the package org.apache.log4j and its sub-packages in the parent class loader are hidden and will be loaded in the module's class loader. All classes in the package javax.servlet and its sub-packages will be loaded from the parent class loader and will never be overridden in the module's class loader. The class loader uses inverse class loading. [ 361 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Deployment Plans
GBeans
The gbean element defines a GBean that will be deployed as part of the module. The schema diagram for this element is shown below:
The name attribute of the gbean element specifies a unique name for this GBean within this module. This name will be used as a name component in AbstractName, hence AbstractName will be unique, server-wide. The class attribute of the gbean element specifies the fully-qualified name of the Java class containing the GBeanInfo for this GBean. The description of the child elements of gbean is as follows: •
attribute: This element provides a value for the GBean attribute. The name of the GBean attribute is specified using the name attribute of the attribute element. The type of the GBean attribute is specified by using the type attribute of the attribute element. The value of the attribute is specified by the value of this element. [ 362 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Appendix A
•
xml-attribute: This element specifies the value of a particular GBean
•
reference: This element specifies the value of a particular reference for this
attribute in XML format, interpreted by a component running in the system, which converts it to a single value for this attribute. The name of the GBean attribute is specified by using the name attribute of the element.
GBean, in its simplest form. It holds the reference to the GBean that matches the single pattern specified here; if no value is specified it will refer to all the matching GBeans. The name of the GBean reference is specified by using the name attribute of this element. The child elements of this element are as follows: °
groupId: This element specifies the name of the group
containing the module to match. By default is it the wild card '*'.
°
artifactId: This element specifies the name of the module in a
°
version: This element specifies the version number of the module, formatted by dot-separated numbers. If no version is provided it will be defaulted to the latest available version that matches the other criteria.
°
module: The value specified for module should match the file name of the referenced module.
°
type: This element defines the type of the module to be
°
name: This element specifies the name to identify the referenced
specified group to be matched.
matched. The type could be CAR, JAR, EAR, WAR, and so on. If no type is provided, it will be defaulted to the wild card '*'. GBean by.
•
references: This element specifies the value of a particular reference for this GBean if it matches multiple pattern elements. Each pattern element may have groupId, artifactId, version, module, type, and name child elements.
•
xml-reference: This element specifies the value of a particular reference
•
dependency: This element is used to resolve dependencies at the GBean level.
in XML format, which will be interpreted by a component running in the system, which converts it to a single value for this reference. The name of the reference is specified by using the name attribute of this element.
This is normally used only if, for some reason, the GBeans within a module must be started in a certain order that is not reflected in the references between them. Dependencies are specified by using multiple pattern elements. Each pattern element may have groupId, artifactId, version, module, type, and name child elements. [ 363 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Deployment Plans
The following is an example of a GBean definition:
Here, a security realm GBean with name of packt-properties-realm is created using XML. It configures one GBean attribute, with a name of realmName, using an attribute element and two references, namely, ServerInfo using a reference element and LoginModuleConfiguration using an xml-reference element.
[ 364 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Appendix A
Application Client
Application Client deployment plans use the client-environment and server-environment elements to define the environment. The description of these elements is as follows: •
client-environment: This element is used only by Application Client
•
server-environment: This element is used only by Application Client
modules to provide a client module environment setting. It defines elements for storing information , such as the Module ID, dependencies, and a class loader for the client-side application module. This information is used to identify the module in the client container only, and should not be directly used by deployment process. modules to define server-side module environment settings. It defines elements for storing information such as the Module ID, dependencies, and a class loader for the server-side of the client application module. This information is used to identify the module in the server environment only.
[ 365 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Troubleshooting In this Appendix, we will look at troubleshooting server startup, application/ configuration deployment and application/configuration startup problems.
Server startup errors
If any of the configurations fail to start during server startup, the server will automatically be shutdown. Most errors during startup are logged to the command window, as well as to the geronimo.log file under the /var/log directory (//var/log directory in the case of a non-default instance). Here are some common startup errors and ways to resolve these errors.
BindException
A BindException is thrown when a GBean attempts to bind to a port that is already in use by another process on the system. A typical log entry for this kind of error is shown below: 2009-07-14 00:02:14,642 ERROR [GBeanInstanceState] Error while starting; GBean is now in the FAILED state: abstractName="org.apache. geronimo.framework/rmi-naming/2.1.4/car? ServiceModule=org.apache.geronimo.framework/rmi-naming/2.1.4/car, j2eeType=GBean,name=RMIRegistry" java.rmi.server.ExportException: Port already in use: 1099; nested exception is: java.net.BindException: Address already in use: JVM_Bind at sun.rmi.transport.tcp.TCPTransport.listen(TCPTransport.java:249) ...
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Troubleshooting
Some of the reasons due to which this error may occur, and the associated remedies are: •
The server instance is already running in a different server process. There is nothing to do in this case.
•
You are attempting to start a different server instance created using the multiple instances feature provided by Geronimo, and the org.apache. geronimo.server.name system property is not set. Make sure that you set the org.apache.geronimo.server.name system property correctly, by using the GERONIMO_OPTS environment variable.
•
You are attempting to start a different server instance created using the multiple instances feature provided by Geronimo, and the org.apache. geronimo.server.name system property is set correctly. The PortOffset property in the config-substitutions.properties file under //var/config may not have been set correctly. Set the PortOffset property so that the conflict is resolved. Remember that this property is used to offset the server ports when using multiple instances within the same installation.
IllegalArgumentException due to a wrong instance name
An IllegalArgumentException is thrown when you attempt to start a non-existent server instance. A message similar to the following is logged to the console: 11:49:26,439 ERROR [GBeanInstanceState] Error while starting; GBean is now in the FAILED state: abstractName="org.apache.geronimo.framework/j2ee-system/2.1.4/car? ServiceModule=org.apache.geronimo.framework/j2ee-system/2.1.4/car, j2eeType=GBean,name=ServerInfo" java.lang.IllegalArgumentException: Server directory is not a directory: C:\book\temp\geronimo-tomcat6-javaee5-2.1.4\wrong_inst at org.apache.geronimo.system.serverinfo.BasicServerInfo.deriv eBaseServer(BasicServerInfo.java:187) ...
To resolve this problem, specify the correct instance name in the org.apache. geronimo.server.name system property.
[ 368 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Appendix B
InvalidConfigurationException
An InvalidConfigurationException is thrown when a configuration that the server is attempting to start does not exist. One reason due to which this can happen is with the multiple server instances feature, when a configuration deployed through one server instance is undeployed through a different server instance, which results in entries corresponding to that configuration being left out of the config.xml files. A typical error message logged in this case looks like the following: org.apache.geronimo.kernel.config.InvalidConfigException: Could not locate configs to start: [packt-samples/helloworld/1.0/war] at org.apache.geronimo.system.main.EmbeddedDaemon. doStartup(EmbeddedDaemon.java:167)
To resolve this problem, edit the config.xml file and remove the problematic configuration entries.
Deployment errors
In this section, we will look at some common deployment errors and how these errors can be resolved.
MissingDependencyException
A MissingDependencyException is thrown when a configuration or repository artifact specified as a dependency in the application, or the configuration being deployed does not exist on the server. The following is a typical error message displayed during deployment: Error: Unable to deploy mywebapp-1.0.war: Unable to createconfiguration for deployment load of default/mywebapp-1.0/1.0/war failed Error starting configuration gbean default/mywebapp-1.0/1.0/war Missing dependency: default/non-existant/1.0/jar
[ 369 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Troubleshooting
The following is a typical message logged to Administration Console when deploying from Deploy New portlet: org.apache.geronimo.common.DeploymentException: Unable to create configuration for deployment at org.apache.geronimo.deployment.DeploymentContext. createTempConfiguration(DeploymentContext.java:150) Caused by: org.apache.geronimo.kernel.repository. MissingDependencyException: Missing dependency: default/non-existant/1.0/jar at org.apache.geronimo.kernel.config.ConfigurationResolver.resolve (ConfigurationResolver.java:113) ...
To resolve this error, make sure that the parent configurations declared in the dependencies exist on the server. You can use the Repository Viewer portlet to view a list of artifacts in the repository. Click on the artifact in the portlet to get help on how to use the artifact as a dependency.
XmlException—Invalid deployment descriptor An XmlException can occur due to an erratic deployment plan, or if the deployer is unable to recognize an element. The following is an example of a deployment exception due to an element in the deployment plan not being recognized:
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Appendix B service@http://geronimo.apache.org/xml/ns/deployment-1.2 persistence@ http://java.sun.com/xml/ns/persistence' instead of 'tomcat-clusteringwadi@http://geronimo.apache.org/xml/ns/tomcat-clustering-wadi-1.2' here Descriptor:
packt-samples helloworld-cluster 1.0 war
/helloworld-cluster
at org.apache.geronimo.deployment.xmlbeans.XmlBeansUtil. validateDD(XmlBeansUtil.java:187) ...
In this example, the error is due to the element not being recognized, as the org.apache.geronimo.configs/tomcat6-clusteringbuilder-wadi/2.1.4/car is not running when deployment was attempted. To resolve this kind of error, start the builder configuration and deploy the application again.
DuplicateDeploymentException
A DuplicateDeploymentException is thrown when an EJB module contains EJBs with the same names as the EJBs already running on the server. This is because the deployment-ids created for the EJBs are same as the running EJBs. A typical log message for this error is given below: 2009-07-17 01:03:17,421 ERROR [GBeanInstanceState] Error while starting; GBean is now in the FAILED state: abstractName="packtsamples/myejbapp/2.0/jar? J2EEApplication=null,j2eeType=EJBModule,name=packt-samples/ myejbapp/2.0/jar"
[ 371 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Troubleshooting org.apache.openejb.DuplicateDeploymentIdException: Application cannot be deployed as it contains deployment-ids which are in use: app: C:\book\geronimo-tomcat6-javaee5-2.1.4\var\temp\geronimodeployer5436850122084871803.tmpdir\myejbapp.jar myejbapp/MySessionBean myejbapp/MyEjb3ServiceBean myejbapp/MyEjb3ServiceBean2 myejbapp/MyEjb3ServiceBean3 at org.apache.openejb.assembler.classic.Assembler. createApplication(Assembler.java:438) ...
This error can be overcome by setting the openejb.deploymentId.format system variable, in order to override the default setting that is causing the conflict. See http://openejb.apache.org/3.0/system-properties.html and http://openejb.apache.org/3.0/jndi-names.html for more details.
Runtime errors
In this section, we will look at some runtime errors that can occur and how these errors can be resolved.
LoginException—No LoginModules configured
A LoginException occurs when the security realm configured in a web application is not running on the server. A warning message similar to the following will be logged to the geronimo.log file�. 2009-07-17 00:48:58,234 WARN [TomcatGeronimoRealm] Login exception authenticating username "system" javax.security.auth.login.LoginException: No LoginModules configured for test-realm ...
To resolve this error, make sure that the configured security realm is running. You can use the Security Realms portlet to view all of the security realms running on the server. To avoid running the application while the security realm is stopped, you should add a dependency on the security realm configuration to your application's deployment plan, so that the security realm is started automatically before starting your application.
[ 372 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
client-environment element 132, 365 default-subject element 133 ejb-ref element 132 elements 131 gbean-ref element 132 message-destination element 133 realm-name element 133 resource-env-ref element 133 resource-ref element 132 resource element 133 server-environment element 365 server-environment, dependencies element 131 server-environment, hidden-classes element 131 server-environment, inverse-classloading element 132 server-environment, moduleId element 131 server-environment, non-overridable-classes element 131 server-environment, suppress-default-environment element 132 server-environment element 131 service-ref element 132 service element 134 application deployment descriptor 96, 357 application deployment plan 97, 358 Application EARs portlet 256 application local JNDI context about 219, 220 ejb-local-ref element 223 ejb-ref element 222, 223 gbean-ref element 228 message-destination-ref element 225, 226 persistence-context-ref element 226, 227 persistence-unit-ref element 227, 228 resource-env-ref element 222 resource-ref element 221 service-ref element 224, 225 ApplicationLog4jConfigurationGBean used, for logging 332, 333 application logging, configuring about 327 Java Logging API used 333 log4j used 327 SLF4j logging adapter used 333, 334
[ 375 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
application security about 180 application-scoped security realm 196 EAR application security, configuring 196 EJB application security, configuring 185 run-as and default subjects 192 web application security, configuring 180, 181, 183, 184, 185 Applications portlets, Administration Console about 17, 255 App Clients portlet 257 Application EARs portlet 256 Deploy New portlet 255 EJB JARs portlet 256 J2EE connectors portlet 257 Plan Creator portlet 257 System Modules portlet 256 Web App WARs portlet 256 artifactId 31 ArtifactResolver 341, 342 ASF 8, 75 Assembler class 27 attribute element 362 attributes, GBean about 343 GBeanInfoBuilder.addAttribute() method 343 magic attributes 344 MySampleGBean class 343
B Bean-managed persistence 124 Bean-managed transactions 144 BindException, Server startup errors 367, 368 BIO HTTP connector, attributes address 269 port 269 uniqueName 269 blocking IO (BIO) 268 boot() 337 BootStrap class loader 35 brokerName attribute 76 brokerUri attribute 76 buildConfiguration() 44
C CA about 161 portlet 164 calculateTax method 26 car-maven-plugin 235 Certificate Signing Request. See CSR Certification Authority. See CA ciphers 165 class loader architecture, Apache Geronimo about 35, 36 BootStrap class loader 35 ClassLoader Viewer portlet 35 default class loading behavior, modifying 36, 37 j2ee-system class loader 35 modules 37 classLoader attribute 344 ClassLoader Viewer portlet 263, 264 client-scoped, database pool scopes 50 client-scoped pool creating 64-66 clientAuth 165 clientAuthRequired 166 Client Security Service. See CSS ClockGBean 235 Clock interface 235 Cluster 307 Clustered Helloworld-cluster application about 317 workers.properties, updating 317-320 clustering 307 CMP 9 command-line deployer used, for creating server-wide JMS resources 86 used, for deploying database pool 61 commit() method 146 Common Object Requesting Broker Architecture. See CORBA Common Secure Interoperability Version 2. See CSIv2 protocol Common Security Interoperability. See CSI compoundSecMech, child elements GSSUP 204 identityTokenTypes 204
[ 376 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
type 31 version 31 configurations, persistable attributes configurationData 30 ManageableAttributeStore, reference to 30 parents, list 30 ConfiguredEncryption GBean 164 connectionfactory-interface 60 connector 63 connector attributes 165, 166 Console Navigation pane 56 constructor, GBean about 345 GBeanInfoBuilder.setConstructor() method, parameters 345 MySampleGBean class, excerpt 346 constructor injection 27 container-managed transactions rolling back, ways 143 setRollbackOnly() method 143 transaction attribute, values:about 142 Container Managed Persistence. See CMP context-param element 105 CORBA about 199 concepts 199 EJBs, exposing 200 EJBs, referencing 209 Naming service 199 ORB 199 Security services 200 support in Geronimo 200 createModule() method 45 Cryptographic message digests 168 cryptographic security about 154 Certificate Authority (CA) portlet 164 JSSE keystores 154, 155 keystore, preparing for using with SSL 162 keystore preparing, for using with SSL 163 keystores portlet 155 passwords, protecting 164 CSI 200 CSIv2 protocol 150 CSR generating, for private key 161
[ 377 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
CSS about 200 creating 209 CSS, creating compoundSecMech, schema diagram 210 cssConfig, child elements 210 GSSUPDynamic elements 212, 213 GSSUPStatic elements 212 identity tokens 213 sasMech, schema diagram 213 SSL element 211 SSL element, child elements 211 supports and requires elements, values 211 cssConfig, child elements compoundSecMech 210 compoundSecMechTypeList 210 description 210 custom server assemblies 245, 246
D database pool application-scoped database pool, accessing from different application 74 application-scoped database pool, accessing from same application 74 scopes 50, 51 server-scoped database pool, accessing 70-73 using, in application 70 database pools, embedded Derby database jdbc/ActiveDS 154 jdbc/ArchiveDS 154 jdbc/juddiDB 154 MonitoringClientDS 153 NoTxDatasource 153 SystemDatasource 154 updating 153 database pools, scopes about 50 application-scoped 50 client-scoped 50 Server-wide 50 Database Pools portlet, Geronimo Administration Console 16, 52, 254 dataDirectory attribute 76 dataSource attribute 76
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
deploy/undeploy, GShell command 285 deployer access, securing 151, 152 deployment, errors DuplicateDeploymentException 371, 372 MissingDependencyException 369 XmlException 370, 371 deployment architecture, Apache Geronimo about 42 configuration builder 43, 44 deployer 42, 43 DeploymentWatcher 47 hot deployment 46 module builder 44 module builder, extension 45 naming builder 46 repository 43 deployment descriptor about 96, 357 application client deployment descriptor 96, 357 application deployment descriptor 96, 357 EJB deployment descriptor 96, 357 resource adapter deployment descriptor 96, 357 types 96, 357 web deployment descriptor 96, 357 deployment plan, Geronimo-specific about 358 application client deployment plan 358 application deployment plan 358 EJB deployment plan 358 resource adapter deployment plan 358 web deployment plan 358 deployment plans about 97 application client deployment plan 97 application deployment plan 97 EJB deployment plan 97 resource adapter deployment plan 97 server-specific deployment plans 98 web deployment plan 97 DeploymentWatcher 47 Deploy New portlet used, for creating server-wide JMS resources 86 using 56- 61
E EAR sample application 137-140 EAR application security configuring 196 EARConfigBuilder 44 Eclipse about 290 downloading 290 EditableConfigurationManager about 340 addGBeanToConfiguration 341 removeGBeanFromConfiguration 341 EJB 8 ejb-local-ref element 223 ejb-ref element 222, 223 EJB annotation 107, 108 EJB applications about 112 annotations 113 EJB deployment plan 116 sample 118, 119 EJB applications, sample about 118-120 deploying 120 JMS resources, deploying 120 web application, deploying 120 EJB application security configuring 185 EJB sample application, running 190, 191
[ 379 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
entity bean security, configuring 191, 192 method permissions, configuring 188 method permissions, declaring in deployment descriptor 185-187 principals, mapping to roles in EJB deployment plan 189 roles defining, annotations used 188 security roles, defining 188 security roles, defining in deployment descriptor 185 EJBContext.getUserTransaction() 144 EJB deployment descriptor 96, 357 EJB deployment plan 97, 358 EJB deployment plan, EJB applications about 116 environment element 116 jndiEnviromentRefsGroup 116 message-destination element 117 security element 117 web-service-binding element 117 EJB deployment plan, enterprise beans ejb-name element 118 jndi-name element 118 local-jndi-name element 118 tss-link element 118 tss element 118 EJB deployment plan, schema openejb-jar2.2.xsd db-syntax-factory element 117 ejb-ql-compiler-factory element 117 enforce-foreign-key-constraints element 117, 118 relationships element 118 EJB JARs portlet 256 EJBs, exposing through CORBA EJB, configuring to use TSS 205 sample application 205-209 sample EJB application, deploying 209 sample EJB application, running 209 Target Security Service (TSS), creating 200, 201 EJBs, referencing through CORBA Client Security Service (CSS), creating 209 EJB reference, configuring to use CSS 214 sample, deploying 217 sample, running 217 sample CSS 215-217
sample web application, CORBA EJBs accessing 214 EJB web service about 135 deploying 140, 141 Embedded DB portlets, Administration Console DB Info portlet 258 DB Manager portlet 258-260 embedded Derby database BUILTIN, authentication method 153 database pools, updating 153, 154 LDAP, authentication method 153 securing 152, 153 enterprise applications about 127 deployment plan 127 enterprise applications, deployment plan elements 128 environment element 128 ext-module element 128, 129 module element 128 security element 129 service element 129 Enterprise JavaBeans. See EJB environment element about 358 defining, in namespace 358 dependencies, import 360 dependencies element 360 hidden-classes element 360 in deployment plan 361 inverse-classloading element 360 moduleId, artifactId 359 moduleId, groupId 359 moduleId, type 360 moduleId, version 359 moduleId element 359 non-overridable-classes element 360 suppress-default-environment element 361 error-page element 105 external-path 63
F farm deployment about 321 sample application, running 322, 323 [ 380 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
farming about 320 cluster member, configuring 320 farm deployment, using 321 sample application running, farm deployment used 322, 323 filter-class element 102 filter-name element 102 filters about 101 filter-class element 102 filter-name element 102 FilterConfig 102 param-name element 102 param-value element 102 servlet-name element 102 url-pattern element 102
testing, GBean web app sample used 353-355 gbean-ref element 228 gbean-ref tag 220 GBean configuration ActiveMQ 76 ActiveMQPort property 78 Administration Console used 78 useShutdownHook property 77 gbean element attribute element 362 child elements 362 dependency element 363 name attribute 362 reference element 363 reference element, artifactId 363 reference element, groupId 363 reference element, module 363 reference element, name 363 reference element, type 363 reference element, version 363 references element 363 xml-attribute element 363 xml-reference element 363 GBeanInfoBuilder.addAttribute() method, parameters manageable parameter 343 name parameter 343 persistent parameter 343 type parameter 343 GBeanInfoBuilder.addInterface() method, parameters intf parameter 346 manageableAttributes parameter 346 persistentAttributes parameter 346 GBeanInfoBuilder.addOperation() method, parameters parameterTypes parameter 345 returnType parameter 345 GBeanInfoBuilder.addReference() method, parameters name 345 namingType 345 type 345 GBeanInfoBuilder.setConstructor() method, parameters parameterNames parameter 345 [ 381 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
multiple server instances, running from single installation 315-317 security realm 174 security standards 149 server directory, securing 150, 151 Single sign-on (SSO) 196, 197 support 145 transactions, support 145 WADI 308 Geronimo, services Kernel 335- 337 geronimo/start-client, GShell command 284 geronimo/start-server, GShell command 283 geronimo/stop-server, GShell command 284 geronimo/wait-for-server, GShell command 284 Geronimo Administration Console, Apache Geronimo Applications portlets 17 Database Pools portlet 16 DB Info portlet 18 DB Manager portlet 18 Deploy New portlet 16 Information portlet 15 Java System Info portlet 15 JMS Resources portlet 16 JMS Server portlet 16 Plan Creator portlet 17 Plugins portlet 17 Repository portlet 16 Server Logs portlet 15 Users and Groups portlet 17 Web Server portlet 16 Geronimo Eclipse Plugin. See GEP getAbstractNameFor() 336 getArtifactResolver() 340 getAttribute() 336 getBaseDirectory() 338 getBootTime() 337 getBuildDate() 338 getBuildTime() 338 getClassLoaderFor() 336 getConfiguration() 340 getConfigurationID() method 44 getCopyright() 338 getDependencyManager() 335
[ 382 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
H hidden-classes 36 hidden-classes element 360 high-level architecture, Apache Geronimo 32, 33 horizontal cluster 307 HTTP connectors adding 269 APR HTTP connector, adding 270 attribute column 269 BIO HTTP connector, attributes 269 description column 269 NIO HTTP connector, adding 270 type column 269 value column 269 HTTPS connectors about 164, 271 Jetty HTTPS connectors 166 SSL configurations, attributes related to 272 Tomcat HTTPS connectors 165 HTTP session activation listener 104 HTTP session attribute listener 103
[ 383 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
I IDE 290 identity tokens, CSS ITTAbsent 213 ITTAnonymous 213 ITTPrincipalNameDynamic 214 ITTPrincipalNameStatic 213 identity tokens, TSS about 205 ITTAbsent 205 ITTAnonymous 205 ITTDistinguishedName 205 ITTPrincipalNameGSSUP 205 ITTX509CertChain 205 schema diagram 204 IllegalArgumentException, Server startup errors 368 Information portlet 252 Information portlet, Geronimo Administration Console 15, 251 init() lifecycle method 101 init-param tag 101 initContext() method 45 installing GEP 292-297 installModule() method 45 Integrated Development Environment. See IDE interface, GBean about 346 GBeanInfoBuilder.addInterface() method, parameters 346 MySampleGBean, excerpt 346 intf parameter, GBeanInfoBuilder.addInterface() method 346 InvalidConfigurationException, Server startup errors 369 inverse-classloading 37 inverse-classloading element 360 Inversion of Control. See IoC invoke() 336 IoC 10, 24 isConfiguration() 339
J j2ee-system class loader 35 J2EE connectors portlet 257 JAAS 150 JAAS login modules about 166 login modules, for authentication 166 JACC 150 Java Authentication and Authorization Service. See JAAS Java Authorization Contract for Containers. See JACC Java Database Connectivity (JDBC) API 49 Java EE 5 development tools 20 Java EE 5 samples 21 Java EE application, deploying about 96 annotations 106 deployment, plans 98 deployment descriptor 96, 97 deployment plans 97 deploy tool 98, 99 filter 101, 102 from administration console 100 listener 102-104 Servlets 100, 101 through GShell 100 web application, sample 112 web deployment descriptor 105, 106 web modules 100 Java EE application server 49 Java EE specifications deployment descriptor, types 357 Java Logging API. See JUL JavaMail 134 Java Message Service. See JMS Java Naming and Directory Interface. See JNDI Java System Info portlet, Geronimo Administration Console 15, 252
[ 384 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Java Virtual Machine. See JVM javax.naming.Context.bind method 220 jaxws/wsgen, GShell command 287 jaxws/wsimport, GShell command 287 JaxWS 39 JSR 88 39 JCA 1.5 94 Jetty 9 Jetty HTTPS connectors about 166 clientAuthRequired 166 keyStore 166 secureProtocol 166 trustStore 166 Jetty specific configuration, web deployment plan compact-path element 112 host element 112 session-manager element 112 virtual-host element 112 JMS 75 JMS listeners, JMS server admin 275, 276 JMS resource, scopes about 78 application-scoped 78 application client-scoped 78 server-wide 78 JMS resources creating 78, 79 using, in application 90- 93 JMS resources, creating application-scoped JMS resources, creating 86-88 application client-scoped JMS resources, creating 89, 90 server-wide JMS resources, creating 79 JMS Resources portlet, Geronimo Administration Console 16, 255 JMS server admin about 275 JMS listeners 275, 276 JMS Server portlet, Geronimo Administration Console 16, 253 JMX server access, securing 151, 152 JMX Viewer portlet 260, 261 JNDI 219
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
listener-class element 104 listStores() 339 loadConfiguration() 340 loadGBean() 336 LocalAttributeManager about 341 config-substitutions.properties file 341 config.xml file 341 SMTPHost property 341 locale-encoding-mapping-list 106 local JNDI context. See application local JNDI context log4j command console 328-330 geronimo.log file, logging to 328, 329 logging, ApplicationLog4jConfigurationGBean used 332 separate log file, logging to 330, 331 used, for application logging configuring 328 Logger.getLogger() API 325 logging about 325 configuring 326 frameworks 325 logging, configuring about 326 client-log4j.properties 327 client.log file 327 configuration files 326 deployer-log4j.properties 327 deployer.log file 327 log files 327 server-log4j.properties 327 server-log4j.properties file 327 server.log file 327 logging, frameworks about 325 Apache Log4j 325, 326 Java Logging API 326 Log4j 325, 326 SLF4J 326 LoginException, runtime errors 372 login modules, for authentication CertificatePropertiesFileLoginModule 171, 172 GeronimoGroupPrincipal 172
[ 386 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
GeronimoUserPrincipal 172 LDAPLoginModule 169-171 PropertiesFileLoginModule 167, 168 SQLLoginModule 168, 169 login modules, for special purpose about 172 FileAuditLoginModule 172 GeronimoPasswordCredentialLoginModule 173 NamedUsernamePasswordCredentialLoginModule 173 RepeatedFailureLockoutLoginModule 173 Log Manager 252
groupId 359 type 360 version 359 MOM 75 Monitoring console about 276 graph, adding 279, 280 server, adding 277-279 view, creating 280, 281 Monitoring portlet 253 multiple server instances running, from single installation 315- 317
N name 60 name parameter, GBeanInfoBuilder.addAttribute() method 343 name parameter, GBeanInfoBuilder.addOperation() method 345 name parameter, GBeanInfoBuilder.addReference() method 345 NamingBuilder instances 46 namingType parameter, GBeanInfoBuilder. addReference() method 345 nodes 307 non-blocking IO (NIO) 268 non-overridable-classes 36 non-overridable-classes element 360
O Object Management Group. See OMG objectName attribute 344 Object Request Broker. See ORB OMG 199 openejb.jndiname.format system property 229 operations, GBean GBeanInfoBuilder.addOperation() method 345 GBeanInfoBuilder.addOperation() method, parameters 345 ORB 199
[ 387 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
P PAM framework 150 param-name element 101 param-value element 101 parameterTypes parameter, GBeanInfoBuilder.addOperation() method 345 persistence-context-ref element 226 persistence-unit-ref element 227, 228 persistentAttributes parameter, GBeanInfoBuilder.addInterface() method 346 Plan Creator portlet, Geronimo Administration Console 17, 257 pluggable Administration Console about 237 architecture 238 extension, developing 238-242 Pluggable Authentication Module. See PAM framework plugin developing 231 installing 236, 237 list 237 project, creating 232-236 plugin, installing Administration Console used 236, 237 deploy.bat script used 236 deploy.sh script used 236 GShell used 236 install-plugin command used 236 list-plugins command used 237 plugin catalog 47 plugin repository 48 plugins about 47 catalog 47 customer server assemblies 48 extensible administration console 48 repository 47 Plugins portlet 243, 244 Plugins portlet, Geronimo Administration Console 17 POJO web services 135 pool editing 66, 67
importing, from another application server 67-69 PortalContainerServicesGBean 242 private-classes 36 PropertiesFile login module about 167 groups properties file, sample 167 options 168 users properties file, sample 167 PropertiesFile login module, options digest option 168 encoding option 168 groupsURI 168 usersURI 168
R reference element about 363 groupId 363 module 363 name 363 type 363 version 363 references, GBean about 344 GBeanInfoBuilder.addReference() method 344 GBeanInfoBuilder.addReference() method, parameters 345 MySampleGBean class, excerpt 345 references element 363 registerShutdownHook() 337 reloadConfiguration() 340 removeGBeanFromConfiguration, EditableConfigurationManager 341 RentCalculator class 25 Repository portlet, Geronimo Administration Console 16, 254 resolve() 338 resolve(URI) 338 resolvePath() 338 resolveServer() 338 resolveServer(URI) 338 resolveServerPath() 338 resource-env-ref element 222 resource-ref element 221
[ 388 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
resource adapter deployment descriptor 96, 357 resource adapter deployment plan 97, 358 resource annotation env-entry value 107 name attribute 106 ResourceBindingsFormat, Global JNDI 229 ResourceBindingsNameInNamespace, Global JNDI 229 ResourceBindingsNamePattern, Global JNDI 229 ResourceBindingsQuery, Global JNDI 229 restartConfiguration() 340 returnType parameter, GBeanInfoBuilder. addOperation() method 345 rollback() method 146 run-as and default subjects, application security application configuring, to use credential store 193 configuring 194 credential store 192, 193 message-driven bean security, configuring 196 sample EJB application, running 195 runtime, errors LoginException 372
S sasMech about 204 schema diagram 213 secureProtocol 166 security-constraint 105 security-role 105 security realm about 174 creating, ways 174 deployment plan 179 principal, wrapping 180 Security Realms portlet, using 174-178 security services on client side 200 on server side 200 security standards CSIv2 protocol 150
JAAS 150 JACC 150 Java Authentication and Authorization Service (JAAS) 149 PAM framework 150 server-environment element 365 server-scoped database pool accessing 70-73 server-wide, JMS resources scope 78 server-wide database pool Administration Console Wizard, using 51-55 command-line deployer, using 61 creating 51 Deploy New portlet, using 56-61 GShell, using 62 Scopes 50 unlisted drivers, installing 56 server-wide JMS resources, creating Administration Console Wizard used 79-85 command-line deployer used 86 Deploy New portlet used 86 GShell used 86 server directory securing 150, 151 var/config 151 var/derby 151 var/repository 151 var/security 151 var/security/keystores 151 server directory structure bin directory 41 configuration files 41 etc directory 41 lib directory 41 schema directory 41 var|config directory 41 var|derby directory 41 var|log directory 41 var|security|keystores directory 41 var|security directory 41 server directory structure, configuration files artifact_aliases.properties 41 client-log4j.properties 42 client_artifact_aliases.properties 42 config-substitutions.properties 41 config.xml 41
[ 389 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
deployer-log4j.properties 42 groups.properties 42 server-log4j.properties 42 users.properties 42 ServerInfo, APIs getBaseDirectory() 338 getBuildDate() 338 getBuildTime() 338 getCopyright() 338 getCurrentBaseDirectory() 338 getVersion() 338 resolve() 338 resolve(URI) 338 resolvePath() 338 resolveServer() 338 resolveServer(URI) 338 resolveServerPath() 338 Server Logs portlet, Geronimo Administration Console 15 Derby Log Viewer 252 Log Manager 252 Server Log Viewer 252 Web Access Log Viewer 252 Server Log Viewer 252 Server portlets, Administration Console about 251 Apache HTTP portlet 253 Information portlet 251, 252 Java System Info portlet 252 JMS Server portlet 253 Monitoring portlet 253 Server logs portlet 252 shutdown portlet 252 Thread Pools portlet 253 Web Server portlet 253 Server startup, errors about 367 BindException 367, 368 IllegalArgumentException 368 InvalidConfigurationException 369 service-ref element 224 service-ref element, elements port 137 service-completion 136 service-ref-name 136 ServiceConfigBuilder 43
Services portlets, Administration Console Database Pools portlet 254 JMS Resources portlet 255 Repository portlet 254 servlet-class element 101 servlet-mapping element 101 servlet-name element 101, 102 servlet context attribute listener 103 servlet context listener 102 servlet request attribute listener 103 servlet request listener 103 Servlets about 100 init() lifecycle method 101 init-param tag 101 param-name element 101 param-value element 101 servlet-class element 101 servlet-mapping 101 servlet-name element 101 session-config element 105 setAttribute() 336 setRollbackOnly() method 143 shutdown() 337 Shutdown portlet 252 Simple Logging Facade for Java. See SLF4J single-pool 60 Single sign-on. See SSO SLF4J about 326 using, over log4j 333, 334 SLF4j logging adapter used, for application logging configuring 333, 334 Spring 39 SQL login module database connectivity using JDBC, options 169 digested passwords using, options 169 digest option 169 encoding option 169 jdbcDriver option 169 jdbcPassword option 169 jdbcURL option 169 jdbcUser option 169
[ 390 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
SQL login module, options groupSelect 168 userSelect 168 SSL element, attributes handshakeTimeout 202, 211 hostname 202 port 202 SSL element, child elements requires 202, 211 supports 202, 211 trustGroup 203, 211 sslProtocol 165 SSO 196, 197 startConfiguration() 340 startGBean() 336 startRecursiveGBean() 336 stopConfiguration() 340 stopGBean() 336 suppress-default-environment 37 suppress-default-environment element 361 System class loader 35 System Modules portlet 256
T Target Security Service. See TSS TaxCalculator class 25 Thread Pools portlet 253 Tomcat HTTPS connectors algorithm 165 ciphers 165 clientAuth 165 keyAlias 165 keyStore 165 keyStoreType 165 sslProtocol 165 trustStore 165 trustStorePass 165 trustStoreType 165 Tomcat specific configuration, web deployment plan cluster 111 cross-context element 110 disable-cookies element 111 host element 110 jndiEnviromentRefsGroup element 111 listener-chain element 111
manager element 111 tomcat-realm element 111 valve-chain element 111 TranQL 11 TranQL framework 49 TranQL RAR files 50 transaction about 142 annotations 143 Bean-managed transactions 144 container-managed transactions 142 in web applications 146, 147 session bean example, container-managed transactions used 142 support in Geronimo 145 timeout, setting 145 transaction, isolation levels read committed 145 read uncommitted 145 repeatable read 145 serializable 145 transaction, support in Geronimo transaction, isolation level 145, 146 transactions, in web applications 146, 147 transaction timeout, setting 145 transaction-caching 60 transaction attribute annotations 143 transaction attribute, values mandatory value 143 never value 143 NotSupported value 143 required value 142 RequiresNew value 142 supports value 143 transaction attribute, values 142 troubleshooting deployment, errors 369 runtime, errors 372 Server startup, errors 367 trustStore 165, 166 trustStorePass 165 TSS about 200 creating 200
[ 391 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
TSS, creating authentication mechanism 203, 204 compoundSecMech, child elements 204 compundSecMech block 203 identityTokenTypes block 204, 205 SSL block 202 SSL element, attributes 202 SSL element, child elements 202 supports and requires elements, values 203 tssConfig element, child elements 201 tssConfig element, elements 201 tssConfig element, child elements compoundSecMech 201 compoundSecMechTypeList: 201 description 201 SECIOP 201 SSL 201 type 31 type parameter, GBeanInfoBuilder.addAttribute() method 343 type parameter, GBeanInfoBuilder.addReference() method 345
U uninstallConfiguration() 340 unlisted drivers installing 56 unloadConfiguration() 340 unloadGBean() 336 unregisterShutdownHook() 337 url-pattern element 102 Users and Groups portlet, Geronimo Administration Console 17 UserTransaction object 146 useShutdownHook attribute 76 useShutdownHook property 77
V var/config 151 var/derby 151 var/repository 151 var/security 151 var/security/keystores 151 version 31 vertical cluster 307
W WADI about 308 deployment descriptor, updating 308, 309 deployment plan, updating 308, 309 org.apache.geronimo.configs/clustering// car 308 org.apache.geronimo.configs/wadi-clustering//car 308 WADI integration of Tribes 308 Web Access Log Viewer 252 Web app in Geronimo 310 Web Application Distribution Infrastructure. See WADI web application security tag 182 configuring 181, 182 geronimo-web.xml file, points 184 sample web application, running 185 web.xml file, points 181 Web App WARs portlet 256 web deployment descriptor about 96, 357 context-param element 105 error-page element 105 jndiEnvironmentRefsGroup 106 jsp-config element 105 locale-encoding-mapping-list 106 login-config 105 message-destination 106 mime-mapping element 105 security-constraint 105 security-role 105 session-config element 105 welcome-file-list element 105 web deployment plan about 97, 108, 358 geronimo-web-2.0.1.xsd, graphical representation 108 Jetty specific configuration 111 Tomcat specific configuration 110 Tomcat specific configuration element 111
[ 392 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
web deployment plan, schema geronimoweb-2.0.1.xsd container-config 109 context-root 109 environment 109 jndiEnvironmentRefsGroup 109 message-destination 109 persistence 109 security 109 security-realm-name 109 service 109 web-container 109 work-dir 109 web modules 100 Web Server administration about 268 AJP connectors 273 HTTP connectors 269-271 HTTPS connectors 271, 272 Web Server Logs 274, 275 Web Server Logs 274, 275 Web Server portlet, Geronimo Administration Console 16, 253 web services about 135 EAR, sample application 137-140 EJB web service, deploying 140, 141 EJB web services 135
POJO web services 135 port-completion Type element 135 port Type element 136 service-completion Type element 135 service-ref element, elements 136, 137 Web Tools Platform. See WTP welcome-file-list element 105 WorldClock plugin 246, 247 WTP 20, 289
X xa-transaction 60 XA pool creating 69, 70 xml-attribute element 363 xml-reference element 363 XmlException, deployment errors 370, 371
Y Yoko, Apache 11
Z ZIP file, Apache Geronimo downloading 12
[ 393 ]
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Thank you for buying
Apache Geronimo 2.1 Quick Reference
Packt Open Source Project Royalties
When we sell a book written on an Open Source project, we pay a royalty directly to that project. Therefore by purchasing Apache Geronimo 2.1, Packt will have given some of the money received to the Apache Geronimo project. In the long term, we see ourselves and you—customers and readers of our books—as part of the Open Source ecosystem, providing sustainable revenue for the projects we publish on. Our aim at Packt is to establish publishing royalties as an essential part of the service and support a business model that sustains Open Source. If you're working with an Open Source project that you would like us to publish on, and subsequently pay royalties to, please get in touch with us.
Writing for Packt
We welcome all inquiries from people who are interested in authoring. Book proposals should be sent to [email protected]. If your book idea is still at an early stage and you would like to discuss it first before writing a formal book proposal, contact us; one of our commissioning editors will get in touch with you. We're not just looking for published authors; if you have strong technical skills but no writing experience, our experienced editors can help you develop a writing career, or simply get some additional reward for your expertise.
About Packt Publishing
Packt, pronounced 'packed', published its first book "Mastering phpMyAdmin for Effective MySQL Management" in April 2004 and subsequently continued to specialize in publishing highly focused books on specific technologies and solutions. Our books and publications share the experiences of your fellow IT professionals in adapting and customizing today's systems, applications, and frameworks. Our solution-based books give you the knowledge and power to customize the software and technologies you're using to get the job done. Packt books are more specific and less general than the IT books you have seen in the past. Our unique business model allows us to bring you more focused information, giving you more of what you need to know, and less of what you don't. Packt is a modern, yet unique publishing company, which focuses on producing quality, cutting-edge books for communities of developers, administrators, and newbies alike. For more information, please visit our website: www.PacktPub.com.
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
Apache Struts 2 Web Application Development ISBN: 978-1-847193-39-1
Paperback: 384 pages
A beginner’s guide for Java developers 1.
Design, develop, test, and deploy your web applications using Struts 2 framework
2.
No prior knowledge of JavaScript and CSS is required
3.
Apply the best of agile development techniques and TDD techniques
4.
# Step-by-step instructions and careful explanations with lots of code examples
Apache MyFaces Trinidad 1.2: A Practical Guide ISBN: 978-1-847196-08-8
Paperback: 300 pages
Develop JSF web applications with Trinidad and Seam 1.
Develop rich client web applications using the most powerful integration of modern web technologies
2.
Covers working with Seam security, internationalization using Seam, and more
3.
Get well-versed in developing key areas of web applications
4.
A step-by-step approach that will help you strengthen your understanding of all the major concepts
Please check www.PacktPub.com for information on our titles
Download at WoweBook.Com
This material is copyright and is licensed for the sole use by Jillian Fraser on 20th November 2009 111 Sutter Street, Suite 1800, San Francisco, , 94104
