HierarchicalMap Tutorial - Intermediate Level

HierarchicalMap is an interface. So anyone can implement it. This tutorial is based on BasicHierarchicalmap, a reference implementation of HierarchicalMap.

Following subjects are covered in this tutorial:

Basic Level
1. Getting Started
2. Creating Structure
3. Recovering the Data
4. Interacting with Collections
5. Restructuring the Map

Intermediate Level
6. Working with Stream
7. Working with XML
8. Handling Large XML
9. Accessing Data Base
10. Accessing Preferences

Advanced Level
11. Template Filling
12. .NET Interoperability
13. Runtime schema validation
14. Writing Application

(Javascript must be enabled to allow syntax highlighting for source code snippets in this tutorial)

Basic Level

The HierarchicalMap interface is composed by three main sets of methods and some helper methods:

Following is our first sample code:

HierarchicalMap map = new BasicHierarchicalMap();
map.put("Greeting", "Hello World!");
	 
System.out.println(map.get("Greeting"));

As you can see, HierarchicalMap behaves exactly like HashMap when simple key is used.

Now, we can create a more complex structure:

Each circle, or node, represents an instance of HierarchicalMap and the rectangle, or leaf, represents any other objects. A node can map subsequent nodes (this is the case of "Order" and "Address"), or can map leaves, e.g. java.lang.String, (this is the case of "type", "City", "State" and "Zip Code").

The following snippet of code will create a data structure representing the data shown above:

//create a HierachicalMap containing first address
HierarchicalMap address1 = new BasicHierarchicalMap();
address1.put("type", "Billing");
address1.put("City", "Sta Clara");
address1.put("State", "CA");
address1.put("ZIP Code", "95054");
//add the address to newly created hmap
HierarchicalMap hmap = new BasicHierarchicalMap();
hmap.add("Order/Address", address1);
//create another HierachicalMap containing second address
HierarchicalMap address2 = new BasicHierarchicalMap();
address2.put("type", "Shipping");
address2.put("City", "São Paulo");
address2.put("State", "SP");
address2.put("ZIP Code", "04717-004");
//add the second address to hmap
hmap.add("Order/Address", address2);

The method "add" also has another signature in which it receives only the "key" and return an empty map appended under that "key". Then, the second address can be added using the following code instead:

//create another HierachicalMap containing second address
HierarchicalMap address2 = hmap.add("Order/Address");
address2.put("type", "Shipping");
address2.put("City", "São Paulo");
address2.put("State", "SP");
address2.put("ZIP Code", "04717-004");

Once the structure is filled, you can query the data inside:

System.out.println(hmap.get("Order/Address/City"));
System.out.println(address2.get("State"));

The lines above will produce the following output:

Sta Clara
SP

Note that the get operation will recover a single data, which we stipulated to be the first data inserted. So even having two cities in the structure, the first one (Sta Clara) was retrieved in the example above. On the other hand, the return for the state was SP because we retrieved the first state from address2 node. If you need to obtain entire set of objects with same key you should use getAll instead:

//example using getAll wich returns a Collection of objects
//matching the key
java.util.Collection val 
                = hmap.getAll("Order/Address/City");
//get the iterator to printout all the objects returned
java.util.Iterator itr = val.iterator();
while(itr.hasNext()) {            
    System.out.println(itr.next());
}

The code above will produce the following output:

Sta Clara
São Paulo

Iterating with the structure will give the most intersting result:

//first, get all the addresses
java.util.Collection addresses 
                   = hmap.getAll("Order/Address");
//for each address in addresses
java.util.Iterator adritr = addresses.iterator();
while(adritr.hasNext()) {
    System.out.println("Address");
    //get the first address wich is a HierarchicalMap
    HierarchicalMap address 
                   = (HierarchicalMap)adritr.next();
    //get the entrySet to iterate with its children,
    //i.e. City, State and ZIP code
    java.util.Set set = address.entrySet();
    java.util.Iterator itr = set.iterator();
    while(itr.hasNext()) {
        //printout the pair key value for each entry
        java.util.Map.Entry entry =
            (java.util.Map.Entry)itr.next();
        System.out.println(entry.getKey() + " : " +
            entry.getValue());
    }
    System.out.println();
}

This will produce the following output:

Address
type : Billing
City : Sta Clara
State : CA
ZIP code : 95054
Address
type : Shipping
City : São Paulo
State : SP
ZIP code : 04717-004

Although the structure used so far is in conformation with XSD recommendation, it is not possible to take advantage of HierarchicalMap. Information organized in such way, does not allow the direct access to inner data (e.g. get the shipping State). This "direct access" can be achieved with a little restructuring on the HierarchicalMap. Thus, we can implement a following method for instance:

public static void denormalize(HierarchicalMap map,
                    String field, String keyField) {
    //first, remove all fields and 
    //substitute with empty map
    Collection col = map.removeAll(field);
    HierarchicalMap newMap = map.add(field);
    //iterate through removed fields
    Iterator itr = col.iterator();
    while(itr.hasNext()) {
        //for each object removed check it if it is a node
        //(i.e. instance of HierarchicalMap)
        Object o = itr.next();
        if(o instanceof HierarchicalMap) {
            //if so, try to get the value of key field 
            //where the node, will be added
            Object key = ((HierarchicalMap)o).get(keyField);
            if(key != null) {
                newMap.add(key.toString(), o);
            }
        }
    }
}

With the above method, we can transform the original map to the following structure:

Now, we can query the map like this:

//call denormalize method defined earlier to reorganize
//the structure from Figure 7 to Figure 8
denormalize(map,"Order/Address","type");
		
//now fetch the desiered information directly
System.out.print("Shipping State: ");
System.out.println(map.get("Order/Address/Shipping/State"));
System.out.print("Billing State: ");
System.out.println(map.get("Order/Address/Billing/State"));

The result will be:

Shipping State: SP
Billing State: CA

The following method can be written to reorganize the map back to the original structure:

public static void normalize(HierarchicalMap map,
                    String field, String keyField) {
   //first, remove all fields
   Collection col = map.removeAll(field);
   Iterator itr = col.iterator();
   while(itr.hasNext()) {
      //for each object removed check it if it is a node
      //(i.e. instance of HierarchicalMap)
      Object o = itr.next();
      if(o instanceof HierarchicalMap) {
         //Then, add each sub-node under field, but 
         //setting a new field containing the key 
         //in which the sub-node was referred
         Iterator itr2 = 
             ((HierarchicalMap)o).entrySet().iterator();
         while(itr2.hasNext()) {
            Entry e = (Entry)itr2.next();
            if(e.getValue() instanceof HierarchicalMap) {
               HierarchicalMap newMap = 
                    (HierarchicalMap)e.getValue();
               //note that it is using put instead of add
               //to ensure uniqueness of the key field
               newMap.put(keyField, e.getKey());
               map.add(field, newMap);
            }
         }
      }
   }
}

Actually, this is all about HierarchicalMap. As you can see, it is as simple as that.

Though, there are many intersting and sometimes complex application for this simple interface.

Continue to Intermediate Level