Products

Hammurapi

Hammurapi rules

jIncarnate

Supporting libraries

Common library

Enterprise extensions

Mesopotamia

Contact us

Discussion board

Newsletter

Hammurapi 5 Quick Start Guide

Description	This document describes how to set up Hammurapi 5 and automatically review Java source code.
Id	152
Last modified	Mon Dec 31 20:09:37 EST 2007
GUID	6addcef94fed050f6eb041b7782fefb0fdd7a2f9
Glossary	Hammurapi glossary

---

Introduction

This document describes how to set up Hammurapi 5 and automatically review Java source code. Hammurapi 5 is a componentry for automated code reviews. As such this document is not a dogma but a guide to action which helps you make first steps toward implementing your code governance processes.

How it works

• Mesopotamia parses source files and stores parsed information in the database. Parsed files are represented by Term 268Scan object. Mesopotamia First Steps describes how to load source files to Mesopotamia repository.
• Hammurapi retrieves Term 268Scan from the database and iterates over its Term 267Source units and Term 269Language elements. Each object is passed to Term 284inspectors' inspect() method with compatible parameters. See HammurapiRulesUserGuide.pdf for more details.
• Inspectors inspect language elements and source units and can post Term 283Violations, Term 313Warnings or Metrics.
• Term 283Violations, Term 313Warnings and Metrics posted by inspectors are collected by Hammurapi and stored to the database.
• Hammurapi Web application is used to render review results.

Bundle

The simplest way to start with Hammurapi 5 is to use Hammurapi 5 bundle, which includes all products constituting the code review solution plus JBoss Web to serve reports. Ant is not included.

• Download and unzip the bundle
• Start run.bat or run.sh in jboss/bin directory. Wait for the server to start up.
• Run Ant in the installation directory.
• Open http://localhost:8080/hammurapi/ URL in your Web browser to browse reports.
• Stop JBoss Web server when you are done.

The bundle reviews Java source files in the directory specified in review.src property, which defaults to test. You set the property in the command line. See Hammurapi 5 Ant task documentation for more details.

Assembly

If, for whatever reason, the bundle doesn't fit your needs, you can assemble your own solution from pieces as described in this section.

Installation

• Download mesopotamia-3.3.0.0.zip. Install Mesopotamia and load source files to be reviewed into a Mesopotamia repository as described in the Mesopotamia First Steps guide. Don't forget to set MESOPOTAMIA_HOME environment variable.
• Download Hammurapi rules and install as described in the manual.
• Download , unzip it to some directory, e.g. C:\Tools\Hammurapi.
• Download , unzip it to inspectors\java subdirectory in the Hammurapi installation directory, e.g. C:\Tools\Hammurapi\inspectors\java.

Initialize database

Hammurapi uses a relational database to store review results. The database initialization script is packaged in the Hammurapi jar file. In this example we will use the same HSQLDB database for storing parsed source files (Mesopotamia repository), and review results. There is a utility class to execute the script and create tables in HSQLDB server running on localhost on default port. If you are planning to use another database then you should extract the script (Hammurapi.sql) from the jar file and execute it in the target database console tool. Please note that SQL syntax might have to be adjusted for the target database.

Here is how to execute the InitDatabase utility class:

You should see output like this:

Run review

Reviews are executed by biz.hammurapi.review.Reviewer class. This class has main() method which allows to execute reviews. hammurapi.bat in Hammurapi distribution invokes this method. If you run this batch file without parameters it will print usage information and exit. In order to review code you have to provide the following parameters:

• Term 268Scan number
• Inspector set url (as described in Hammurapi rules documentation)
• Number of threads for multi-threaded review execution (optional, defaults to 1)
• HSQLDB server and port (optional, defaults to localhost)

To review scan 0 with Java inspectors use the following command line:

Browse report

Hammurapi 5 uses a web application to render review results. Web files are located in the web directory. Build a WAR file using buildwar.bat. Out of the box the web application uses direct JNDI reference to the datasource java:/HammurapiDS. Hammurapi distribution contains hammurapi-ds.xml datasource definition for JBoss. web.xml file contains commented out resource reference section. If you use JBoss all you need to do it to build a war file and then copy hammurapiweb.war and hammurapi-ds.xml to the deploy directory of JBoss. Then open http://localhost:8080/hammurapiweb/ URL in your browser. Make sure that hsqldb.jar in JBoss is of the same version as in Mesopotamia (1.8).

If you use some other application server or servlet container, you should create a datasource pointing to the Mesopotamia/Hammurapi database. You might have to modify the web.xml to adjust JNDI name of the datasource. You can also uncomment resource reference section in the web.xml file. Some application servers complain when a web application uses direct JNDI references.

Next steps

Once you achieved basic review functionality you can rearrange Hammurapi code review components to meet your exact needs. For example:

• Embed code reviews into your development process, e.g. add review tasks to build files to every build automatically reviewed.
• Extends Java Term 271language module with additional loaders for deeper reviews.
• Write additional Term 271language modules, e.g. HTML, XML, JavaScript or JSP modules to review not only Java sources, but all application artifacts.
• Write additional Term 284inspectors for Java or other languages.
• Extend HammurapiWeb web application.

If online reports are going to be accessed by many people, it is recommended to deploy a caching proxy server in front of the Hammurapi Web application.