The basics of installing and configuring the Hudson continuous integration engine to continuously build and test Oracle Application Development Framework applications
By John Stegeman
Published March 2010
When two or more developers work together on a project, issues can arise when code from one developer has a negative effect or interaction when code from multiple developers is integrated together. In a “traditional” development environment, where the code from different developers may be developed in isolation for relatively long periods of time, these code integration issues may be found much later than when the code was actually written; this makes integration issues much more difficult to identify and solve than if they were discovered early in the cycle. A newer development technique, known as continuous integration, or CI, was created to deal with this problem. In CI, the code from multiple developers is integrated and tested together early in the development process and often during the process. This helps identify issues soon after the code causing the problems is developed; in this way, the offending code is still fresh in the developers' mind and can be rectified much more quickly. In addition, finding issues early prevents them from growing and becoming more complex, more difficult, and more expensive to diagnose and resolve.
Because building and testing applications can be resource-intensive, adopting CI usually means adopting a tool to automatically perform the application build and tests. A quick search of the internet will turn up a myriad of CI servers; at the time of this writing, the Wikipedia article on CI had no fewer than 35 examples! CI servers work by waiting for some triggering condition (such as a regular schedule, a developer request, or code's being committed by a developer to the version control system) and executing a full build of the application and running appropriate tests. Teams using this approach often follow a procedure that requires developers to commit their code at least as often as daily. Developers who commit code that causes the CI build to “break” (fail tests or not compile) are often given some undesirable public task to perform, as an incentive to avoid breaking the build. There are even semi-whimsical hardware devices that provide a public display, such as flashing lights, of the build status.
With so many CI servers available, how can you choose one? For Java-based projects, there are several popular choices:
For this article, I chose to use Hudson, for two reasons: first, it is a very popular system, and as such, it has a large user community as well as a wide variety of plug-ins (later on in the article, you'll see how useful plug-ins can be). The second reason is that Hudson, unlike the similarly popular Cruise Control, is quite easy to set up and configure.
We will be using the Oracle Application Development Framework (Oracle ADF) 11g application, unit tests, and UI tests that were developed in earlier articles in this series. If you haven't been following along, you can download the source code here: oracle.com/technology/pub/files/adf-development-essentials-sample.zip. For the purposes of this article, I have also removed the “everyone” access from my VisualSVN Subversion repository and required login credentials for access so we can see how this works. If you do this, I recommend that you create a user in the Subversion server specifically for Hudson, so that any action Hudson might perform (such as tagging a build) will be recorded as having been done by Hudson. If you have an unsecured repository, you can skip the steps related to providing the credentials.
Developer Laptop (Windows Vista)
Oracle JDeveloper 11g installed
Oracle Database 11g and Visual SVN installed (for testing)
CI Server (Virtual Machine)
OpenSUSE 11.2RC2 and Hudson installed
The first thing we need on the CI server is a JDK capable of running Hudson. My CI server already has a JDK installed, which is fine for running Hudson, but it's a bit out-of-date to use as the JDK for compiling an Oracle ADF 11g application. Although Hudson has the ability to download and install JDKs and versions of Ant automatically, it does take a bit of setup and configuration to do so. So, for this article, I'll download and install an updated JDK manually. For Ant, however, you may recall from the JUnit article of this series that we need to copy a few JAR files from an Oracle JDeveloper install into the Ant library directory, so we cannot use the automatic install capability and must install Ant and copy the libraries ourselves.
To install Ant, just download it from the Ant Web site and unzip it to an appropriate directory on the CI server. As mentioned in the Ant article, you'll need to copy junit.jar and ant-weblogic.jar from an Oracle JDeveloper 11g installation (they are in <install_directory>/jdeveloper/ant/lib) into the lib directory of the Ant you downloaded and unzipped.
The next step is to tell Hudson which JDKs and Ant installations we are interested in. Fortunately, all the Hudson configurations are done via a Web interface and are quite straightforward. To start, browse to the Hudson URL (by default) and click the Manage Hudson link. Then, on the Manage Hudson page, click Configure System. On this page, you can set up both the JDK and Ant installations. To start, click the Add JDK button in the JDK section. Uncheck the Install Automatically check box, provide a memorable name (I suggest using the JDK version), and provide the location where the JDK is installed. On my system, it looks like this:
Figure 1: JDK configuration
Next, do the same thing to add an Ant installation. Here's mine:
Figure 2: Ant configuration
Click the Save button to save the configuration. Now you'll be able to use the configured JDK and Ant installations when you create the Hudson jobs.
Creating a Build-and-Test-on-Commit Job
Let's start by creating a Hudson job that has the following characteristics:
This job will show the basic capabilities of Hudson. Once we have the job working, we'll look at how you can add more functions to the job by using Hudson plug-ins. To get started, just navigate to the Hudson home page, located at http://<your_host_name>:8080. Getting started is easy: the center of the Hudson page invites you to “please create new jobs to get started.” Click the create new jobs link now. Hudson will ask you to name the job and pick the type of job to create. Let's call this job Build and Test OTN Trunk (we will build from the project “trunk” in Subversion; this type of job is a “free-style software project,” in Hudson terminology. Fill in the information, and click OK:
Figure 3: New job information
The next screen displayed is where you do the entire job configuration itself. If you like, provide a description of the job in the provided field. Rather than explain the purpose of each option on the job screen, let's just look at the minimum options we need in order to set up the job. To specify which JDK to use when running Ant tasks, configure the build as a parameterized build in Hudson and add a string parameter to set the value of JAVA_HOME. To do this, check the This build is parameterized check box and use the drop-down to add a string parameter named JAVA_HOME, with the value pointing to the appropriate JDK on your system, like this:
Figure 4: Setting the JAVA_HOME parameter for the build job
The next item we need to provide is the source code management (SCM) information. Because we are using Subversion, click the radio button for Subversion to see the Subversion options. The only item we need to provide is the Subversion URL from which we want to build. Provide the URL of the “trunk” of the application in your environment. Mine is http://hostname/svn/otn/trunk.
Figure 5: Subversion URL for the job
As you can see from the screen shot, Hudson knows right away that the Subversion repository is secured. Click the enter credential link, and provide the username and password for the repository. In the new window that opens, provide the appropriate details and click OK. Mine looks like this:
Figure 6: Subversion authentication
Next we need to set up a build trigger. Our description indicates that we want the CI job to run when changes are committed to Subversion. Hudson calls this option Poll SCM. Once you click the Poll SCM check box, you'll be able to indicate the schedule for polling. The schedule is specified in the same format you would use for a cron job (you can click the field's Help button for more information and some examples). Let's have our job poll for a new commit once every minute so that we don't have to wait too long to see things happen:
Figure 7: SCM polling schedule
Next you'll add the steps you want Hudson to execute as part of the build. Based on the description we created for this job, we want Hudson to execute the following Ant tasks:
Let's add the first build step by clicking the Add build step list and choosing Invoke Ant:
Figure 8: Adding an Ant-based build step
You can then specify the Ant version to use from the list. Because we have multiple Ant build.xml files in our project, we need to click the Advanced button to tell Hudson which one to use. The build file should be specified relative to the Subversion URL. So to tell Hudson to execute the model.compile task in the Model project's Ant build, xml, fill in the information like this:
Figure 9: Build step for the model.build Ant task
You can then follow the same steps to add two more build steps for the other two Ant tasks. The configuration for these two tasks looks like this:
Figure 10: Remaining build steps
The final step in configuring the job is to set up any postbuild actions for the job. As you can see from looking at the options, you can do a variety of things, such as e-mailing someone to let them know how the build went or publishing Javadocs. The one we are interested in is publishing the JUnit test results; check the appropriate check box, and tell Hudson (again, using a path relative to the Subversion URL, Hudson needs the “trunk” at the start of the path) where the JUnit test results are located:
Figure 11: Specifying the test results location
You can now click the Save button to save the job. Hudson will run the build job for the first time. You can see the progress by clicking the ENABLE AUTO REFRESH link in the upper right corner. Once the build starts, you should see the Build History widget start to animate (you can always click the Build Now link if Hudson doesn't start the build automatically):
Figure 12: Build status widget
If you want to monitor the build in detail, you can click the link of the build and then click the Console Output link to see the output. The console view can also be very helpful for figuring out why a build failed (bad job configuration, compile failure, and the like). For example, in one iteration, I had mistyped the Ant task in one of the build steps and saw this in the console view:
Figure 13: Console log from a failed build
When I went back to the Hudson Dashboard page, I saw that my job status was failed (indicated by a big red ball) and that the project “weather” was stormy:
Figure 14: A stormy project
Hopefully your first build will be successful. Once you have corrected any errors and have a successful build, the dashboard should start to reflect a more settled picture:
Figure 15: A more settled picture
Note that the project “weather” doesn't get sunny immediately, because of the recent build failure. Once you have a string of successful builds, your project should be nice and sunny. You can click any of the links in the Last Success or Last Failure columns to see information about the build. For example, when I clicked on the last successful build, I got a status page for the build:
Figure 16: Single build status page
From there, I could look at the test results:
Figure 17: Test results
. . . and even drill down to individual tests:
Figure 18: Individual test results
To test the build triggering, you can make a change to the application in Oracle JDeveloper 11g and commit the change. Soon thereafter, you should notice in the Hudson dashboard that Hudson has detected the change and initiated the build:
Figure 19: Build in progress
Once the build has completed and you click the build number, you can see an indication that the build was triggered by an SCM change, the comment provided by the developer for the commit, and even a detail link showing who did the commit and what files that person changed:
Figure 20: Build result showing initiation by SCM change
To enable you to run the UI tests, the application must first be bundled into an Enterprise Archive (EAR) file and installed on the Oracle WebLogic Server for testing. Additionally, the UITests project will need an Ant script that runs the UI tests. Showing you how to do these step-by-step would make this article much too long, so I'll summarize the steps here:
Once you have performed these preliminary steps, you can create the Hudson job. The setup of the Hudson job is quite similar to that of the first job you created; the only differences are these:
Figure 21: Job executing at midnight every day
Figure 22: Build step for UI tests
Figure 23: Publishing UI test results
Once you have created the job, ensure that Oracle WebLogic Server and Selenium RC are started (you could add steps in the Ant task to start these if you like) and execute the job. If you watch on the build server, you'll eventually see a browser window pop open (thanks to Selenium RC) and execute the UI tests. If all is working well, you'll start to see two "sunny" projects in your Hudson dashboard:
Figure 24: Two "sunny" projects!
You should now have all the tools you need in your arsenal to be able to develop Oracle ADF applications effectively in teams, automate project builds with Ant, automate unit testing with JUnit, automate UI testing with Selenium, and continuously integrate and test your application with Hudson. I hope you have found these articles helpful.
Special thanks to Timo Hahn for helping me (via the great OTN JDeveloper and ADF Forum) to debug why my application wasn't working on a standalone Oracle WebLogic Server but was working fine in Oracle JDeveloper. Remember that the OTN JDeveloper and ADF Forum can be a great place for you to find assistance (remember to search first) as well as to help others.
John Stegeman ( http://stegemanoracle.wordpress.com) is an Oracle ACE director (Oracle Fusion Middleware) and the principal architect in the EMEA region for Cambridge Solutions, a global BPO and IT services firm. He has been working with Oracle products since 1990 and with Oracle JDeveloper since Release 3.