|Java tools and libraries|
Hammurapi architectureThis 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.
Figure 1. Components.
ComponentsFigure 1 shows most important components of Hammurapi. It doesn't show libraries, RDBMS (HSQLDB), and servlet container (Apache Tomcat).
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.
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 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 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 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 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 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.
Figure 2. Data 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
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 modelThis section describes significant Hammurapi database tables and relationships between them.
Figure 3. Data model.
Tables related to code parsing.
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 keeps metadata for supported programming languages. Metadata includes names parser classes, and language element classes.
Source unit represents state of a source file (e.g. .java file) at particular point of time (scan time).
Scan is a colleciton of source units. It is a snapshot of repository state.
Tables related to code review.
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 indicates a (potential) problem in source code. Inspectors report violations during review. Hammurapi stores reported violations into the database.
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 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.
AssociationsRelationships between tables.
Repository can have zero or more scans. Scan belongs on one repository.
Repository can have zero or more source units. Source unit belongs to one repository.
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.
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 can contain zero or more violations. Violation belongs to one report.
Report can contain zero or more measurements. Measurement belongs to one report.
Report can contain zero or more warnings. Warning belongs to one report.
Source unit can contain zero or more violations. Violation can be associated with zero or one source unit.
Source unit can contain zero or more measurements. Measurement can be associated with zero or one source unit.
Source unit can contain zero or more warnings. Warning can be associated with zero or one source unit.