Hammurapi architecture

This page provides high level description of Hammurapi architecture. The illustrations are interactive - when mouse is over a shape, a pop-up opens with descirption of the shape. Click on the shape navigates to the shape's description section.

Components

Figure 1 shows most important components of Hammurapi. It doesn't show libraries, RDBMS (HSQLDB), and servlet container (Apache Tomcat).

Hammurapi

Ant task and Eclipse plug-in are front-end components which coordinate work of other parts.

Ant task

The Ant task is used to integrate Hammurapi into the build process. The task has several sub-tasks to load sources to the database, perform review and delete old reports.

Eclipse plug-in

The plug-in provides instant feedback to developers. Both the Ant task and the plug-in use same configuration files to ensure consistency between "development-time" and "build-time" inspections.

Inspector sets

Inspector sets are collections of inspectors. Different types of sources may have to follow different standards. For example, a Swing application will need Swing-specific inspectors and doesn't need J2EE inspectors. Inspector sets are Hammurapi rules' rule sets with inspectors as rules. Inspector sets are one of Hammurapi extension points.

Inspectors

Inspectors are Java classes which perform inspections of language elements of source code, report violations and collect metrics. Inspectors are specialized rules of Hammurapi rules'. One inspector class can have one or more inspecting methods. Inspectors are one of Hammurapi extension points.

Mesopotamia

Mesopotamia is a framework for parsing sources written in different programming languages, storing them in a repository, and representing as Heterogeneous Abstract Syntax Tree, a Heterogeneous Abstract Semantic Graph, or some other data structure. Heterogeniety of language elements, though not mandatory, simplifies inspectors development.

Language modules

Language modules are Java libraries which contain lexers, parsers and Java classes to represent target language's elements. See Java language module JavaDoc for an example of language module structure. Language modules are one of Hammurapi extension points.

Hammurapi rules

Hammurapi rules is a bi-directional, JSR-94 compatible rules engine. Hammurapi uses forward-chaining means of Hammurapi rules to dispatch language elements created by language modules from source files to inspectors, and to collect results (violations, metrics, and warnings). Use of a rules engine allows to implement complex inspection logic where severals inspectors work in concert to detect non-trivial problem.

Information flow

Source files are created/modified by developers and then built into an executable application.

Developer creates/modifies source files. If development is done in Eclipse-based IDE, then developer can obtain instant feedback on potential coding problems by leveraging Hammurapi Eclipse plug-in

Ant task loads configuation from XML files. These files, as well as jar files with inspectors, can be located in a file system, on loaded from a location specified by URL, e.g. from intranet HTTP server.

Eclipse plug-in loads configuration from the same XML resources as the Ant task. The plug-in also requires additional configuration file, which can also be loaded from URL.

Eclipse or Eclipse-based IDE passes sources for review to the plug-in. The plug-in reports violations and warnings to the problem window.

The Ant task stores parsed sources and review results to a relational database. Hammurapi default database is HSQLDB. The database also contains metadata information.

The Ant task parses sources and passes language elements to inspectors. For example, a try-catch block in represented by TryBlock class. Inspectors willing to inspecto try blocks shall implement inspect(TryBlock) method.

The Ant task reads metadata information from the database. Then it stores parsed sources to the database. After that it executes review and stores review results to the database.

In the future it will be possible to store review results to the database directly from the plug-in. It will be a convenient way for developers to report codebase metrics and quality to management on a regular basis, e.g. once a week.

Code quality reports are rendered by a web application. The application also provides repository/database management functions. It is one of Hammurapi extension points.

Hammurapi web application executes in a servlet container. Hammurapi comes bundled with Apache Tomcat. Users may choose to deploy the web application to a different container.

The web application reads data from the database and renders them to HTML.

Rendered HTML is delivered to a web brower.

Manager (or team lead, or architect) browses code quality reports (see sample report).

Data model

This section describes significant Hammurapi database tables and relationships between them.

Mesopotamia

Tables related to code parsing.

Repository

Repository is a collection of source units. Repository corresponds to a software component under code governance. One database may contain multiple repositories. Repository has "time dimension" - each scan represents repository state at some point of time.

Language

Language keeps metadata for supported programming languages. Metadata includes names parser classes, and language element classes.

Source unit

Source unit represents state of a source file (e.g. .java file) at particular point of time (scan time).

Scan

Scan is a colleciton of source units. It is a snapshot of repository state.

Hammurapi

Tables related to code review.

Report

Report table store report name, time and some other information. It is also a hub to which other tables containg review information are connected.

Violation

Violation indicates a (potential) problem in source code. Inspectors report violations during review. Hammurapi stores reported violations into the database.

Measurement

In addition to reporting violations inspectors can collect metrics, e.g. method length, cyclomatic complexity. Metric measurements reported by inspectors are stored in this table.

Warning

Warning indicates a condition which prevented Hammurapi from completing one of tasks. It may be exception thrown from one of inspect() methods, or a syntax error in one of source files. Inspectors may report warnings explicitly. If inspect() method throws exception, that is exception gets converted to a warning.

Associations

Relationships between tables.

Repository - Scan

Repository can have zero or more scans. Scan belongs on one repository.

Repository - Source unit

Repository can have zero or more source units. Source unit belongs to one repository.

Scan - Source unit

Scan can include zero or more source units. Source unit may be part of one or more scans. If some source file didn't change between two scans, then source unit corresponding to file's state will be associated with both scans. If some other file did change between scans, then there will be two source units representing file state at times of the first and the second scans.

Language - source unit

Database may contain zero or more source units for particular programming language (e.g. Java). Source unit has one "root" language. Source units can be "multi-lingual", i.e. employ several languages to parse and represent source unit structure. For example, HTML source unit can contain CSS definitions and JavaScript fragments. There can be only one "root" language from which parsers can "multiplex" to other languages.

Report - Scan

One scan can have zero or more associated reports. For example same scan can be reviewed several times using different inspector sets. Report can be associated with one scan.

Report - Violation

Report can contain zero or more violations. Violation belongs to one report.

Report - Measurement

Report can contain zero or more measurements. Measurement belongs to one report.

Report - Warning

Report can contain zero or more warnings. Warning belongs to one report.

Violation - Source unit

Source unit can contain zero or more violations. Violation can be associated with zero or one source unit.

Measurement - Source unit

Source unit can contain zero or more measurements. Measurement can be associated with zero or one source unit.

Warning - Source unit

Source unit can contain zero or more warnings. Warning can be associated with zero or one source unit.

Extension points

Hammurapi is an extensible solution. The primary extension points of Hammurapi are:

• Development of new inpectors for existing language modules.
• Combining inspectors into new inspector sets.
• Development of additional language modules.
• Adding functionality to the web application.

Hammurapi provides means for extension modules to contribute to the file system, database, and web application web.xml file during installation.