Hammurapi Group

Java tools and libraries

Products

Hammurapi rules

jIncarnate

Supporting libraries

Common library

Enterprise extensions

Mesopotamia

Contact us

Discussion board

Newsletter

This document will walk you step by step through Mesopotamia installation and basic use. By the end of this tutorial you will know how to create Mesopotamia database, store source files to Mesopotamia repository and traverse object tree which represents parsed sources.

Download

Download mesopotamia-3.3.0.0.zip, unzip and install to some directory. In this document I'll assume that you have a directory C:\Tools and all tools are installed under this directory. In this case Mesopotamia shall be installed into C:\Tools\Mesopotamia. Set MESOPOTAMIA_HOME environment variable to C:\Tools\Mesopotamia. We will not use this variable in this tutorial, but it will be needed if you decide to run code review on your sources with Hammurapi.

Then download the Java language module for Mesopotamia, mesopotamia-java-3.5.0.zip.

Start and initialize database

Mesopotamia uses HSQLDB version 1.8. hsqldb.jar is included into Mesopotamia distribution. First of all you have to start the database server. Go to the db folder (C:\Tools\Mesopotamia\db) and execute runServer.bat. The server will start and it will create an empty database Mesopotamia in data folder, if one does not exist already.

Now we have to initialize the new database. It is a two-step process. First of all we have to create database structure. Then we shall load Java language definitions.
To create the structure execute

java -cp lib\hgcommons.jar;lib\hsqldb.jar;lib\mesopotamia.jar;lib\hgee.jar org.mesopotamia.util.InitDatabase

in C:\Tools\Mesopotamia directory. You shall see the following output:

Usage: java [options] org.mesopotamia.util.InitDatabase
Loading biz/hammurapi/persistence/ChunkingStringStorage.sql
Loading org/mesopotamia/Mesopotamia.sql
Loading org/mesopotamia/GlobalParameters.sql

Then load Java module definitions using the following command

java -cp lib\hgcommons.jar;lib\hsqldb.jar;lib\mesopotamia.jar;modules\Java\lib\mesopotamia-java.jar org.mesopotamia.lang.java.util.InitDatabase

The output shall be as follows:

Usage: java [options] org.mesopotamia.lang.java.util.InitDatabase
Loading org/mesopotamia/init.sql
Loading org/mesopotamia/lang/java/v13/language.sql
Loading org/mesopotamia/lang/java/v13/tokenTypes.sql
Loading org/mesopotamia/lang/java/v13/tokenTypesUpdate.sql
Loading org/mesopotamia/lang/java/v13/loaders.sql
Loading org/mesopotamia/lang/java/v13/languageElementClass.sql
Loading org/mesopotamia/lang/java/v14/language.sql
Loading org/mesopotamia/lang/java/v14/tokenTypes.sql
Loading org/mesopotamia/lang/java/v14/tokenTypesUpdate.sql
Loading org/mesopotamia/lang/java/v14/loaders.sql
Loading org/mesopotamia/lang/java/v14/languageElementClass.sql
Loading org/mesopotamia/lang/java/v5/language.sql
Loading org/mesopotamia/lang/java/v5/tokenTypes.sql
Loading org/mesopotamia/lang/java/v5/tokenTypesUpdate.sql
Loading org/mesopotamia/lang/java/v5/loaders.sql
Loading org/mesopotamia/lang/java/v5/languageElementClass.sql

Now we have initialized Mesopotamia database in C:\Tools\Mesopotamia\db\data folder. To browse the database structure start runManager.bat in db folder. Execute SHUTDOWN command to politely bring the server down. After you shut the server down you can backup data directory if you choose so.

NOTE: When you execute SHUTDOWN the manager will report "Connection broken" error. This is how it should be.

Load source files

If you shut down the database server, start it again with runServer.bat. Then start your favorite IDE and create a Java project. Add Mesopotamia jars from C:\Tools\Mesopotamia\lib and C:\Tools\Mesopotamia\modules\Java\lib to the project classpath.

Create class org.mesopotamia.firststeps.Load as shown below

package org.mesopotamia.firststeps;

import java.io.File;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Date;

import javax.sql.DataSource;

import org.mesopotamia.FileSourceIterator;
import org.mesopotamia.Language;
import org.mesopotamia.LanguageSelector;
import org.mesopotamia.Repository;
import org.mesopotamia.RepositoryFactory;
import org.mesopotamia.Scan;
import org.mesopotamia.Source;
import org.mesopotamia.SourceIterator;

import biz.hammurapi.sql.SQLProcessor;
import biz.hammurapi.sql.hypersonic.HypersonicIdentityRetriever;
import biz.hammurapi.sql.hypersonic.HypersonicServerDataSource;

public class Load {

    /**
    * @param args
    */
    public static void main(String[] args) throws Exception {
        DataSource ds = new HypersonicServerDataSource("localhost", "mesopotamia", "", null);
        SQLProcessor processor=new SQLProcessor(ds, null);

        biz.hammurapi.persistence.ChunkingStringStorage stringStorage = new biz.hammurapi.persistence.ChunkingStringStorage();
        stringStorage.setDatasource(ds);
        stringStorage.setIdentityManager(new HypersonicIdentityRetriever());
        stringStorage.setChunkSize(Integer.MAX_VALUE);
        stringStorage.start();

        RepositoryFactory factory=new RepositoryFactory(processor, null, null, null, stringStorage);
        Repository repository=factory.createRepository("Mesopotamia sources");
        System.out.println("Repository: "+repository.getId());

        File file=new File("C:\\Tools\\Mesopotamia\\src");
        Collection rootFiles=new ArrayList();
        rootFiles.add(file);
        SourceIterator si = new FileSourceIterator(rootFiles);

        final Language targetLanguage = new Language("Java", "5", "Java 5");

        LanguageSelector ls = new LanguageSelector() {

            public Language select(Source source) {
                return source.getName().endsWith(".java") ? targetLanguage : null;
            }

        };

        long start = System.currentTimeMillis();

        Scan scan=repository.createScan(si, ls, "As of "+new Date(), "SHA", null, null);
        System.out.println("Done with scan " +scan.getId() +" in "+ ((System.currentTimeMillis()-start)/1000)+" seconds.");

        stringStorage.stop();
    }
}

Run it and you should see output like

Repository: 0
Done with scan 0 in 4 seconds.

Which means that a new repository with id 0 was created and in that repository a scan with id 0 was created. Mesopotamia source files were loaded to the repository in 4 seconds.

Access parse data

We have source files parsed and stored in a Mesopotamia repository. Now we can them in many different ways, e.g. analyze with Hammurapi or use as input model for Transformica.

This section shows how to access data stored in the repository. In this example we'll print names and locations of all method parameters in Mesopotamia. Create Visit class as shown below and run it.

package org.mesopotamia.firststeps;

import javax.sql.DataSource;

import org.mesopotamia.RepositoryFactory;
import org.mesopotamia.Scan;

import biz.hammurapi.sql.SQLProcessor;
import biz.hammurapi.sql.hypersonic.HypersonicIdentityRetriever;
import biz.hammurapi.sql.hypersonic.HypersonicServerDataSource;
import biz.hammurapi.util.Visitor;

public class Visit {

    /**
    * @param args
    */
    public static void main(String[] args) throws Exception {
        DataSource ds = new HypersonicServerDataSource("localhost", "mesopotamia", "", null);
        SQLProcessor processor=new SQLProcessor(ds, null);

        biz.hammurapi.persistence.ChunkingStringStorage stringStorage = new biz.hammurapi.persistence.ChunkingStringStorage();
        stringStorage.setDatasource(ds);
        stringStorage.setIdentityManager(new HypersonicIdentityRetriever());
        stringStorage.setChunkSize(Integer.MAX_VALUE);
        stringStorage.start();

        RepositoryFactory factory=new RepositoryFactory(processor, null, null, null, stringStorage);
        Scan scan=factory.getScan(0);

        long start = System.currentTimeMillis();

        Visitor visitor = new Visitor() {

            public boolean visit(Object target) {
                if (target instanceof org.mesopotamia.lang.java.ParameterDefinition) {
                    org.mesopotamia.lang.java.ParameterDefinition pd = (org.mesopotamia.lang.java.ParameterDefinition) target;
                    System.out.println(pd.getName()+" "+pd.getLocation());
                }
                return true;
            }

        };

        scan.accept(visitor);
        System.out.println("Done with analysing scan " +scan.getId() +" in "+ ((System.currentTimeMillis()-start)/1000)+" seconds.");
        stringStorage.stop();
    }

}

In this code we

Instantiate repository factory,
Retrieve scan with id 0 which we create with Load class
Pass Visitor to the scan. The scan walks the visitor through all language elements in the scan. For each parameter definition we print parameter name and location.

Visualization

A picture is worth a thousand words. You can visualize scans, source units and language elements with Browser, which is part of the common library. This is how to do it:

CompositeVisualizer cv = CompositeVisualizer.getThreadInstance();

cv.addVisualizer(new MesopotamiaVisualizer());

Visualizable v = cv.toVisualizable(scan);

Browser browser = new Browser("Scan 0", v.toTree("Scan 0"));

browser.setVisible(true);

below is a screenshot of visualized Mesopotamia source scan

Scan visualization.