Level: Intermediate Kumar Kishore (kishore.kumar@ustri.com), Director, Java Center of Excellence, US Technology
06 Mar 2007 How many times have you built simple applications and had to use heavyweight application servers to deploy them? Do you know what percentage of the many Java™ Platform, Enterprise Edition (Java EE) features you commonly use? I'd venture to guess only about 10%. Case in point: Apache Geronimo is a stable, open source, Java 2 Platform, Enterprise Edition (J2EE) 1.4-certified application server; but it's also feature rich, fat, and bulky. In an effort to build a simple, lightweight, but useful container for Web applications, the folks at Apache created Apache Geronimo Little-G, a stripped-down version of the original Geronimo application server. Though Little-G is not a J2EE-certified application server, it has most of the commonly used J2EE-compliant features, including a full Web container, a transaction manager, and database connectivity. In this article, you'll discover the features of Little-G and learn how to deploy and run Web applications on it.
The Geronimo platform
No discussion of Little-G and Geronimo is complete without an exploration of the
underlying architecture. The Geronimo platform has a modular architecture. The core
platform is a runtime container for unit service components called GBeans.
Related GBeans are grouped into deployable units called configurations. The
Little-G server uses the modular architecture of the Geronimo platform to build a
lightweight server. Figure 1 shows the internal structure of
Little-G.
Figure 1. The Geronimo platform architecture
You add new services and functionalities by deploying the configuration on the
Geronimo platform. The Geronimo kernel and the basic Geronimo system configuration
form the core platform for all Geronimo servers. Little-G builds on top of this
core by adding a Remote Method Invocation (RMI) naming configuration that provides
naming service functionality. In addition, the RMI naming configuration provides a
thread pool and a plug-in installer. The Java EE server and Java EE security
configurations have the RMI naming configuration as their parent configurations.
The Java EE server configuration implements Java EE management objects, such as a server
domain and server object. The Java EE security configuration implements a Java
Authentication and Authorization Service (JAAS)-based security service and JAAS
login modules, plus it creates a properties file-based security realm that can be
accessed from user applications. On top of the Java EE server sits the transaction
configuration, which provides transaction capability. Finally, the Apache Tomcat
configuration plugs the Tomcat Web container into Geronimo.
In addition to the configurations shown in Figure 1, Little-G consists of the
following deployers:
-
geronimo/geronimo-gbean-deployer/1.1.1/car configuration -- Handles
deployment of Little-G modules
-
geronimo/j2ee-deployer/1.1.1/car configuration -- Handles Java EE
deployments for Web applications
-
geronimo/tomcat-deployer/1.1.1/car configuration -- Deploys Web
applications to a Tomcat Web container
- Three configurations:
-
geronimo/unavailable-ejb-deployer/1.1.1/car -- Handles the unavailability of Enterprise JavaBeans (EJBs)
-
geronimo/unavailable-webservices-deployer/1.1.1/car -- Handles the unavailability of Web services
-
geronimo/unavailable-client-deployer/1.1.1/car -- Handles the unavailability of client application deployers
Little-G services and features
Little-G comes with the following services and features:
Get started with Little-G
You can set up Little-G in one of two ways:
- Download and install the server archive.
- Build the server from source.
If you're interested in building from
source, you must download the source files and run specific Maven goals to build
and create the server. But for this article, you'll be installing the archive, and for that
you need Subversion to download the Geronimo source.
Download and install Little-G
Begin by downloading Geronimo.
There, you'll find UNIX® and Microsoft® Windows® files for
both the Geronimo server and Little-G. Download the Little-G Apache Tomcat compressed
file, and extract it to your GERONIMO_HOME folder, as shown in
Figure 2.
Figure 2. The Little-G directory
As you can see, the directory structure of the Little-G installation is
similar to any Geronimo installation. After all, it's just another Geronimo
incarnation.
Test your Little-G installation
Little-G doesn't come bundled with the console application, so you
can't test the installation by pointing your browser to the console application
URL (http://localhost:8080/console). With Little-G, you must use the
Command-Line Interface (CLI) to interact with the server. Start the server by
issuing either of the following commands from the GERONIMO_HOME/bin
directory:
GERONIMO_HOME\bin> java –jar server.jar
or
GERONIMO_HOME\bin> startup
The server starts and displays the startup information in the command window, as
shown in Figure 3.
Figure 3. Little-G startup
messages
If you see these messages, your Little-G installation is working properly.
Little-G starts the following listeners:
- A naming service listening on port 1099
- A remote login listener on port 4242
- A Tomcat Accelerated Graphics Port (AGP) connector for Apache Web
server integration
- HTTP and HTTP over Secure Sockets Layer
(HTTPS) listeners on ports 8080 and 8443, respectively
- A Java Management Extension (JMX) connector that the deploy tool uses
to deploy applications
You now know how to start the server. Now, to perform a
graceful shutdown, issue the following command from the command window:
GERONIMO_HOME/bin> shutdown –user system –password manager
Change Little-G settings
Most system settings, such as log level and Web listener ports, can be changed
easily with Little-G. The GERONIMO_HOME/var/config/config.xml file holds
persistent settings information. For instance, if you need to change the Tomcat
HTTP listener port, change the value of the port
attribute of the TomcatWebConnector GBean, as shown in
Listing 1.
Listing 1. Config.xml
<module name="geronimo/tomcat/1.1.1/car">
<gbean name="TomcatResources"/>
<gbean name="TomcatWebConnector">
<attribute name="host">0.0.0.0</attribute>
<attribute name="port">8080</attribute>
<attribute name="redirectPort">8443</attribute>
</gbean>
<gbean name="TomcatAJPConnector">
<attribute name="host">0.0.0.0</attribute>
<attribute name="port">8009</attribute>
<attribute name="redirectPort">8443</attribute>
</gbean>
<gbean name="TomcatWebSSLConnector">
<attribute name="host">0.0.0.0</attribute>
<attribute name="port">8443</attribute>
</gbean>
<gbean name="geronimo/tomcat/1.1.1/car?ServiceModule=geronimo/tomcat/1.1.1/car,
j2eeType=GBean,name=TomcatWebContainer">
<attribute name="catalinaHome">var/catalina</attribute>
</gbean>
</module>
|
Similarly, you can change the HTTPS listener port by changing the value of the
port element in the TomcatWebSSLConnector
GBean. The config.xml file is read every time you start the server, and these
attribute values are applied to their corresponding GBeans. The server also updates
this file to reflect changes when new applications are deployed or undeployed. In
general, you can change or provide new values for any GBean in a module by
specifying a corresponding entry in this file. However, if you need to change the
log settings, you must do something different. You must make changes to the
GERONIMO_HOME/var/log/server-log4j.properties file.
Download, deploy, and run sample applications
Because Little-G doesn't come packaged with sample applications, you must
download and deploy them separately. By doing so, you can learn how to deploy and
run Web applications in Little-G.
Download a sample application
Clicking the Sample applications link on the
Geronimo
Documentation page takes you to a listing of sample applications. Click the
Web application security sample link, and download the sample
application. (You can also download the sample application, timereport.zip,
from the Download section). In this sample application,
employees can enter their time card information, and managers can enter time
card information and add new employees. This application uses a
database-based security realm for Web application security.
Set up the database
Note: I'm using a postgreSQL V8.0 database (see the Resources section).
You can use any other database, but my example listings use settings for
postgreSQL.
After you have a running database installation, run the SQL script (config/TimeReportDB.sql, available in timereport.zip in the Download section). This script creates user and group tables that you'll use to set up a database-based
security realm.
Install a database driver to the Little-G repository
You've already seen the Little-G directory structure: The GERONIMO_HOME/repository
directory holds all external libraries. Install the database driver .jar file to this directory. The repository directory structure
holds external libraries in subdirectories following a Maven-based naming
convention, as shown in Figure 4.
Figure 4. The Little-G
repository
You can see that the commons-digester-1.6.jar file resides in the
commons-digester/commons-digester/1.6 directory. This means that if you have an
item with groupID cglib, artifactID cglib-nodep,
version 2.1_3, and type jar, Little-G expects a file with the
name cglib-nodep-2.1_3.jar in the folder
GERONIMO_HOME/repository/cglib/cglin-nodep/2.1_3. To install the
postgresql-8.0.jar file, place it in the postgresql/postgresql/8.0
subdirectory in the repository folder.
Deploy the security realm
The sample application uses a database-based security realm, and you must
install the realm before you install the Web application. Edit the security
realm deployment plan -- config/TimeReportRealm.xml -- to specify dependency
with the postgreSQL database driver .jar file, the JDBC driver class, and the
JDBC connection URL for login module configuration, as shown in
Listing 2.
Listing 2. Security realm configuration deployment plan
<module xmlns="http://geronimo.apache.org/xml/ns/deployment-1.1">
<environment>
<moduleId>
<groupId>console</groupId>
<artifactId>TimeReportRealm</artifactId>
<version>1.0</version>
<type>car</type>
</moduleId>
<dependencies>
<dependency>
<groupId>geronimo</groupId>
<artifactId>j2ee-security</artifactId>
<type>car</type>
</dependency>
<dependency>
<groupId>postgresql</groupId>
<artifactId>postgresql</artifactId>
<version>8.0</version>
<type>jar</type>
</dependency>
</dependencies>
</environment>
<gbean name="TimeReportRealm"
class="org.apache.geronimo.security.realm.GenericSecurityRealm">
<attribute name="realmName">TimeReportRealm</attribute>
<reference name="ServerInfo">
<name>ServerInfo</name>
</reference>
<reference name="LoginService">
<name>JaasLoginService</name>
</reference>
<xml-reference name="LoginModuleConfiguration">
<log:login-config
xmlns:log="http://geronimo.apache.org/xml/ns/loginconfig-1.1">
<log:login-module control-flag="REQUIRED"
server-side="true" wrap-principals="false">
<log:login-domain-name>TimeReportRealm</log:login-domain-name>
<log:login-module-class>
org.apache.geronimo.security.realm.providers.SQLLoginModule<
/log:login-module-class>
<log:option name="jdbcDriver">org.postgresql.Driver</log:option>
<log:option name="jdbcUser">postgres</log:option>
<log:option name="userSelect">
select userid, password from users where userid=?
</log:option>
<log:option name="groupSelect">
select userid, groupname from usergroups where userid=?
</log:option>
<log:option name="jdbcURL">
jdbc:postgresql://localhost:5432/TimeReportDB
</log:option>
</log:login-module>
</log:login-config>
</xml-reference>
</gbean>
</module>
|
The moduleId element specifies a Maven-style name for
this deployment unit (also known as a configuration). This means that you
can refer to this configuration from other configurations using the Uniform
Resource Identifier (URI) common/TimeReportRealm/1.0/car. Also notice that I
have specified a Maven-style dependency definition to the postgreSQL .jar file
in the repository. I have provided values for the JDBC driver class, the
database user name, and a JDBC URL to connect to the database, in which you
have already created the users and usergroup tables.
After you've made the changes to the deployment plan, deploy the configuration
using the following command:
deploy –user system –password manager deploy TimeReportRealm.xml
This command deploys the security realm as a configuration with the name
console/TimeReportRealm/1.0/car. If you need to undeploy the security
realm, use the following command:
deploy –user system –password manager undeploy console/TimeReportRealm/1.0/car
Deploy the Web application
The Web application .war file is available in the release directory
or from the Download section in this article. To deploy the .war file, issue
the following command:
deploy –user system –password manager deploy TimeReport.war
This command deploys the Web application and can be invoked by pointing your
browser to http://localhost:8080/timereport. You can log in as an employee by
typing emp1 as the user name and pass1 as the password.
To log in as a manager, type mgm1 as the user name and pass3 as the password. You can also open the web.xml and geronimo-web.xml
deployment descriptors to learn more about how authentication is defined and
mapped to a security realm.
Where can you use Little-G?
You can use Little-G whenever you need to host simple Web applications that require
no more than a transaction facility and database connectivity. With respect to this
functionality, Little-G provides a complete Web container with all relevant and
necessary Java EE features. You've already seen a simple application that leverages
the built-in Web security features of Little-G. For simple and small Web
applications, Little-G makes good sense.
Conclusion
This article introduced Little-G and the services it offers to Java EE applications and
showed how the modular nature of the Apache Geronimo platform enables creation of a
smaller, lightweight version of Geronimo. You also configured, deployed, and ran
a sample Web application in Little-G. Little-G provides a stripped-down
version of Geronimo, and you can definitely use the modular nature of the Geronimo
platform to start building on Little-G.
Experiment: Add new configurations to provide
services that you want to have supported. This is where the power of Geronimo lies!
Download | Description | Name | Size | Download method |
|---|
| Sample time report application for this article | timereport.zip | 95KB | HTTP |
|---|
Resources Learn
Get products and technologies
Discuss
About the author  | 
| | Kishore Kumar is director of the Java Center of Excellence for US Technology and an
ardent believer in open source systems, cricket, and classical music. He has been a
software engineer and a J2EE architect, and he is the author of many books and
articles, including
Pro
Apache Geronimo
. |
Rate this page
| 
