MegaMap - A simple, unbounded hashtable for Java

MegaMap

A simple, unbounded hashtable for Java

What You Need
The distribution of MegaMap includes the three .jar files you need to use it. Those are:

MegaMap-VERSION.jar
commons-collections-3.1.jar
commons-logging-1.0.3.jar

These three .jar files must be in the classpath of your application. MegaMaps is not very sensitive to the version of Commons Collections or Commons Logging, so feel free to use any version of Commons Collections after 2.0 and any verison of Commons Logging after 1.0.

How To Use MegaMap
MegaMap is very straightforward to use. There are two classes with which the user should become familiar: com.larvalabs.megamap.MegaMap and com.larvalabs.megamap.MegaMapManager. MegaMap is the class that actually provides the put, get, and remove methods that you would expect from a hashtable. The MegaMapManager is responsible for the lifecycle of a MegaMap. It is used to create and destroy MegaMaps.

The best way to demonstrate the use of these classes is with an example. The following main method creates a MegaMap, puts four objects in to the MegaMap, then retrieves and displays one of the objects from the map:

import com.larvalabs.megamap.MegaMapManager;
import com.larvalabs.megamap.MegaMap;

public class MegaTest {

    public static void main(String[] args) {
        try {
            // Get Manager singleton
            MegaMapManager manager = MegaMapManager.getMegaMapManager();
            {
                // Create MegaMap with name "map1"
                //  (the other two parameters will be discussed later)
                MegaMap map = manager.createMegaMap("map1", false, false);
                // Add some objects with Integer keys
                map.put(new Integer(1), "Test Object 1");
                map.put(new Integer(2), "Test Object 2");
                map.put(new Integer(3), "Test Object 3");
                map.put(new Integer(4), "Test Object 4");
                // Retrieve and display one of the objects
                String s = (String) map.get(new Integer(4));
                System.out.println(s);
                // Shutdown the manager
                manager.shutdown();
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Consider this line from the above example:

    MegaMap map = manager.createMegaMap("map1", false, false);

Here, the method MegaMapManager.createMegaMap(String name, boolean persistent, boolean overwriteOld) is called. Each time this method is called, a new MegaMap is created. However, each new MegaMap must have a unique name or else an exception will be thrown. The name must consist of letters, numbers and the underscore character ('_') only. The next parameter, persistent indicates whether a persistent MegaMap should be used. If a MegaMap is labelled as persistent, then it will remain on disk after the virtual machine shuts down. It will be reloaded the next time a MegaMap is created with the same name, unless the last parameter, overwriteOld, is set to true.

Next, consider this line from the example:

    manager.shutdown();

This line shuts down all MegaMaps and does whatever clean-up work is necessary. For non-persistent MegaMaps this is not too important. However, it is vitally important that this is called before the virtual machine is shutdown for persistent MegaMaps. See the full documentation for more information about this requirement.