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.

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

Back to top

Little-G services and features

Little-G comes with the following services and features:

• A Web container that is either Tomcat based or Jetty based
• A Java EE basic server
• A JAAS-based security implementation
• An RMI-based naming service
• A deployer that can deploy GBean configurations
• A deployer that can deploy Web applications
• JDBC connectivity through code from TranQL, an open source implementation for creating persistence engines
• A facility to create and deploy Geronimo plug-ins

  Note: Geronimo plug-ins are similar to Eclipse plug-ins that contain packaged applications or additional functionalities. Geronimo plug-ins encapsulate all deployment information; as a result, you can install them easily without worrying about environment-specific settings.

Back to top

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.

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.

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

Back to top

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.

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

Back to top

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.

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.

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

Back to top

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.

Back to top

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!

Back to top

Download

Information about download methods

Resources

Learn

• Check out the Geronimo home page at apache.org.
  
  
• Visit the Little-G wiki for more information about the server and a link to sample Geronimo applications and the Web application security sample application.
  
  
• Visit the Codehaus home page for more information about TranQL, the open source persistence framework.
  
  
• Check out the developerWorks Apache Geronimo project area for articles, tutorials, and other resources to help you get started developing with Geronimo today.
  
  
• Find helpful resources for beginners and experienced users at the Get started now with Apache Geronimo section of developerWorks.
  
  
• Check out the IBM® Support for Apache Geronimo offering, which lets you develop Geronimo applications backed by world-class IBM support.
  
  
• Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  
  
• Stay current with developerWorks technical events and webcasts.
  
  
• Browse all the Apache articles and free Apache tutorials available in the developerWorks Open source zone.
  
  
• Browse for books on these and other technical topics at the Safari bookstore.
  
  

Get products and technologies

• Download Apache Maven.
  
  
• Download Subversion.
  
  
• I used postgreSQL in this article.
  
  
• The Geronimo Downloads page has links to the technologies and samples discussed in this article.
  
  
• Download the latest version of Apache Geronimo.
  
  
• Download your free copy of IBM WebSphere® Application Server Community Edition -- a lightweight J2EE application server built on Apache Geronimo open source technology that is designed to help you accelerate your development and deployment efforts.
  
  
• Innovate your next open source development project with IBM trial software, available for download or on DVD.
  
  

Discuss

• Participate in the discussion forum.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

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 article

Comments

Back to top

Table of contents

• The Geronimo platform
• Little-G services and features
• Get started with Little-G
• Change Little-G settings
• Download, deploy, and run sample applications
• Where can you use Little-G?
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).

---

• Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
• Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
• Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
• Demo: This demo shows how to use the new Java EE 5 Java Persistence API (JPA) framework.
• Buy: Rational Application Developer

Dig deeper into Open source on developerWorks

Discover knowledge paths

Skill-building guides for open source, Linux, cloud, Java, business analytics, and more.

Special offers