For experts: the reference labeling model

The Recursive Multiple Layout must be used when the label layout should use a specified labeling model that is not the default labeling model ( IlvDefaultLabelingModel , see Labels and obstacles in Java). The Multiple Layout allows you to specify a particular labeling model by using the method setLabelingModel , but when you encapsulate the Multiple Layout into a Recursive Layout, this specification would need to be repeated for each layout instance of each subgraph. This would be inconvenient. However, the Recursive Multiple Layout takes care of this mechanism automatically.

If you implement your own labeling model (subclass of IlvLabelingModel ), you must implement the method:

IlvLabelingModel createLabelingModel(Object subgraph) 

This method should return a new instance of your own labeling model for the input subgraph. The Recursive Multiple Layout uses this method to generate all labeling models for all subgraph from a reference labeling model. Before attaching the Recursive Multiple Layout instance, you can set the reference labeling model in the following way:

recursiveMultipleLayout.setReferenceLabelingModel(myLabelingModel);
recursiveMultipleLayout.attach(myGraphModel);

The reference labeling model is used for the label layout of the top-level grapher. Clones of the reference labeling model obtained by createLabelingModel are used for the label layouts of the subgraphers.

Here is a simple way to perform a label layout recursively:

IlvRecursiveMultipleLayout layout = 
    new IlvRecursiveMultipleLayout(labelLayout);
layout.setReferenceLabelingModel(myLabelingModel);
layout.attach(topLevelGraph);
try {
        IlvGraphLayoutReport layoutReport = layout.performLayout();
        ...
}
catch (IlvGraphLayoutException e) {
        System.err.println(e.getMessage());
}
layout.detach();

If the Recursive Multiple Layout instance is detached from the top level graph model, all sublayouts are automatically detached as well and all labeling models of subgraphs (including the reference labeling model) are disposed of.