coffee-banner.jpg

Setting up Geronimo, your database, and build software

IN PROGRESS

Tim Howe
vsync@quadium.net

Table of Contents

1 Introduction

coffee-jar.jpg

Java is a good language for networked application development for several reasons. Although it's somewhat constrained and verbose there are plenty of well-developed libraries and most programmers have enough familiarity to make sense of Java code. .class and .jar files allow use of third-party or precompiled libraries without worrying about binary architecture or compiling everything from source. Database access is consistent and scalability issues have already been tackled and largely addressed by big industry players. Robust open-source application servers are available. And the JVM also lets you run code from other languages such as Common Lisp, Clojure, Scala, Python, and Ruby.

Although a number of warts remain, Java has improved considerably since its early days. In particular the JIT compilers and virtual machines have gotten quite efficient. While Java is statically compiled to bytecode the reflection APIs allow those used to dynamic languages to do some of what they'd like. The collections framework coupled with generics makes working with data structures much less painful. And annotations allow limited code injection. Dealing with Java EE has also gotten much less painful since removing the need for multiple stub interfaces and XML files per class.

While plenty of documentation is available online, I've had trouble finding resources with complete examples rather than code scenarios. Most seem to give isolated excerpts and/or assume the use of an IDE's code generation facilities. There's also plenty of information on simple scenarios and much less on linking them together in slightly less common but still real-life situations. Finally I've found I had to translate a fair bit of vendor-specific information.

My goal is to provide a concise guide to quickly get productive with Java server development using stable versions of open-source tools. I hope it will save you some of the difficulties I ran into.

2 Prerequisites

2.2 Software

I use the following software and while you're free to swap components, I've had good experiences with them:

Java
go figure
PostgreSQL
excellent open-source object-relational SQL database
Ant
Java build software
ws-xmlrpc
Apache's Java XML-RPC library
Geronimo
Apache's Java EE application server
Apache HTTPD
the famous Web server
Squid
Web proxy/accelerator

2.3 Development environment

workstation.jpg

Don't overlook the importance of a comfortable development environment. While these tools will all run on any modern OS, the experience is certainly simpler on some than on others. For my money I don't think there's a better OS for developers than Gentoo. Ubuntu is the rising star for those who aren't already Unix-heads.

Mac OS X is fine once you get everything installed, but it lacks a standard package manager / ports system and Apple's Java support tends to be variable. Windows runs everything fine but the experience is frustrating, partly due to simple Windows boneheadedness, partly due to different assumptions than the Unix world most development tools have grown up in, and partly due to incomplete work by the Windows packagers of these tools. You'll also find yourself wishing for simple utilities that come with every other OS, and rebooting randomly to clear file locks and so forth.

If at all possible it's to your advantage to work on a system similar to where you'll be deploying, or at least have a virtual machine for testing.

3 Setup

3.1 Base software

Install the following using the appropriate procedure for your operating system:

Make sure all the binaries are available in your path.

3.2 Geronimo

3.2.1 Base Geronimo install

Download the latest stable version of Geronimo (v2.2.1 as of this writing) built with Tomcat.

Unpack it in a suitable location such as /srv/geronimo-tomcat6-javaee5-2.2.1. Start the server with a command such as:

/srv/geronimo-tomcat6-javaee5-2.2.1/bin/geronimo.sh start

This will start the server on port 8080. If you need a different port, edit the file /srv/geronimo-tomcat6-javaee5-2.2.1/var/config/config-substitutions.properties and edit the EndPointURI and HTTPPort properties.

3.2.2 PostgreSQL JDBC driver

Finally you need to install the JDBC driver for PostgreSQL.

  1. Download the "JDBC4" driver from jdbc.postgresql.org
  2. Go to the Repository in your Geronimo console
    (http://localhost:8080/console/portal/Services/Repository)
  3. Upload postgresql-9.1.901.jdbc4.jar
  4. Update the values thusly:
    Group
    org.postgresql
    Artifact
    postgresql
    Version
    9.1-901.jdbc4
  5. "Install"

3.3 Database pool

server-room.jpg

The next step is to create a database and a role (user account) which your application will use to access the database, then tell Geronimo what they are so it can connect on your application's behalf.

From here on your application will simply ask Geronimo for access to a database pool. Geronimo will manage connection pooling, authentication, and all the other bothersome details. Your application doesn't need to know any of the specifics; in fact, the developer of an application might not know what the database is even named in production!

3.3.1 Setting up the PostgreSQL users and database

Create a PostgreSQL database and an associated PostgreSQL user. We'll call our database "testdb" and our user "testuser". You can call them whatever you like but the important thing is that the user should not be the owner of the database. This is because we don't want the application to be able to — in case of a security breach or simple mistake — easily destroy all the data at once or drop tables, schemas, and so forth.

You'll also need to either make your everyday PostgreSQL user the owner of this database (recommended) or do all your database provisioning as a superuser (such as the postgres user).

3.3.2 Telling Geronimo about the database

  1. Go to Database Pools in your Geronimo console
    (http://localhost:8082/console/portal/Services/Database%20Pools)
  2. Select "Create a new database pool: Using the Geronimo database pool wizard"
  3. Create Database Pool – Step 1: Select Name and Database
    Name of Database Pool
    jdbc/testpool
    Database Type
    PostgreSQL Local

    Click "Next".

  4. Create Database Pool – Step 2: Select Driver, JAR, Parameters
    Driver JAR
    postgresql/postgresql/9.1-901.jdbc4/jar
    Database Name
    testdb
    User Name
    testuser
    Password
    testuser's password
    Confirm Password
    testuser's password

    You should be able to leave the other fields at default.

    Click "Deploy".

  5. You should be back at the Database Pools page in your Geronimo console.

    Now we're going to trivially test whether Geronimo can talk to PostgreSQL and connect to the database with the credentials you've given.

    1. Scroll down to the Run SQL section.
    2. Select the new data source you've just created.
    3. Enter the following in SQL Command/s:
      select 42;
      
    4. Click "Run SQL".
    5. You should receive the message "SQL command(s) executed successfully.".

      If you receive the message "An error encountered while executing SQL command(s).", expand the error message by clicking the small '+' symbol. Read what error occured, then try again.

      If you need to change the data source settings simply delete it and go back to "Create a new database pool: Using the Geronimo database pool wizard"

This process should be almost identical for any other database engine with JDBC drivers available.

4 You're on your way

main-screen-turn-on.gif Congratulations! You now have a working Java EE application server with a database pool configured and ready to use.

I have the outline and some notes written on how to write your first application. Although it's not complete you're welcome to read it.

5 Thanks

5.1 Photo credits

coffee berries
subbu
roasted coffee beans
Pierre Camateros
workstation
United States Department of Transportation
server room
torkildr
main screen turn on
AYBABTU

All these images are licensed under Creative Commons BY-SA, with the exception of the workstation image, which is in the public domain, and "main screen turn on" which is from the epic Internet meme. Some have been cropped and/or resized. Please feel free to reuse these images yourself.

5.2 Enjoy this draft

Thanks for viewing this draft article. All rights are reserved. Once I have worked out the content a little more I might place it under a more permissive license. Please contact me with any questions.


Tim Howe   –   <vsync@quadium.net>