Saving layout parameters and preferred layouts

Programmer's documentation > Using graph layout algorithms > Using advanced features > Saving layout parameters and preferred layouts

Explains how to save a graph and its layout parameters and preferred layouts in a file.

Overview of saving

Discusses different ways of storing a graph and its layout parameters.

Saving layout parameters to .ivl files

Gives an example of saving a grapher and its layout parameters to IVL files and explains the mechanism.

Saving preferred layouts to .ivl files

Gives an example of saving the preferred layouts of a grapher to IVL files and explains the mechanism.

Loading layout parameters from .ivl files

Gives an example of loading layout parameters from IVL files and explains the mechanism.

Loading preferred layouts from .ivl files

Gives an example of loading preferred layouts from IVL files and explains the mechanism.

Additional information for expert users

Gives useful information for expert users.

Overview of saving

Important To understand saving better, read section Using the graph model first.

There are many ways to store your graph and your layout parameters:

Diagram components use XML files for the data and CSS files for the rendering parameters.

Diagram components can use a database.

Graphers can be stored in .ivl files.

This topic deals only with .ivl files. It is not relevant for applications that use XML files, CSS files, or databases.

Layout parameters are stored in the layout classes directly, not in the IlvGrapher. The advantage of this is that the layout parameters are independent of the graph model. However, the disadvantage is that a layout parameter setting is lost whenever a graph is saved to an .ivl file and reloaded later. To overcome this disadvantage, the IlvGrapherAdapter class allows you to transfer the graph layout settings to instances of IlvNamedProperty that can be stored in .ivl files and to recover the settings from these named properties at a later time, see Save parameters to named properties.

The following method indicates whether a layout class supports this mechanism:

supportsSaveParametersToNamedProperties();

It returns true if the layout class can transfer the parameter settings to named properties.

Saving layout parameters to .ivl files

The following example shows how to save the IlvGrapher including all layout parameter settings into an .ivl file. The example assumes that an IlvGrapher is attached to three instances layout1, layout2 and layout3.

IlvGrapherAdapter adapter1 = (IlvGrapherAdapter)layout1.getGraphModel();

IlvGrapherAdapter adapter2 = (IlvGrapherAdapter)layout2.getGraphModel();

IlvGrapherAdapter adapter3 = (IlvGrapherAdapter)layout3.getGraphModel();

// transfer the layout parameters to named properties

if (layout1.supportsSaveParametersToNamedProperties())

adapter1.saveParametersToNamedProperties(layout1, false);

if (layout2.supportsSaveParametersToNamedProperties())

adapter2.saveParametersToNamedProperties(layout2, false);

if (layout3.supportsSaveParametersToNamedProperties())

adapter3.saveParametersToNamedProperties(layout3, false);

// assume that adapter1, adapter2 and adapter3 work on the same grapher

// save the grapher with all 3 sets of named layout properties to file

grapher.write("abcd.ivl");

// remove the named layout properties because they are no longer needed

adapter1.removeParametersFromNamedProperties();

adapter2.removeParametersFromNamedProperties();

adapter3.removeParametersFromNamedProperties();

In this example, different grapher adapters of the same IlvGrapher are supposed to be attached to layout1, layout2 and layout3. If, in fact, the same grapher adapter (more precisely, grapher adapters that all work on the same set of nodes and links) is attached to all three layout instances, one call of the removeParametersFromNamedProperties method at the end is sufficient.

Take a look at the mechanism in detail:

String saveParametersToNamedProperties(IlvGraphLayout layout, boolean

withDefaults);

This method creates named properties for the input layout and transfers the complete layout parameter settings to these properties. The property name is an automatically generated, unique string that is returned. If the flag withDefaults is false, the created layout properties are persistent only if they contain a setting that is not the default setting. This means that the default values are not stored in the .ivl file and the file has a smaller size. If the flag withDefaults is true, the created properties are always persistent, that is, the default values are stored in the .ivl file as well.

The named properties that are created require additional memory. Therefore, it is recommended to remove them as soon as they are no longer needed. To remove the named layout properties, you can use one of the following methods:

removeParametersFromNamedProperties

This method removes all named layout properties from the grapher.

removeParametersFromNamedProperties

This method removes only the named layout properties that match the input property name.

removeParametersFromNamedProperties

This method removes all named layout properties that fit the input layout class.

The named layout properties are subclasses of IlvGraphLayoutGrapherProperty, IlvGraphLayoutNodeProperty, and IlvGraphLayoutLinkProperty, see the Java™ API Reference Manual for details of these classes.

Saving preferred layouts to .ivl files

The class IlvDefaultLayoutProvider allows you to specify the layout instances to be used for each graph. The layout provider can then be used for the recursive layout of a nested graph. (For details, see Nested layouts.)

You can set your preferred layouts using one of the methods setPreferredLayout of the class IlvDefaultLayoutProvider and save these preferred layouts to .ivl files using the method:

boolean savePreferredLayoutsToNamedProperties(IlvDefaultLayoutProvider

provider, boolean withParameters, boolean withDefaults, boolean traverse);

The method takes the Layout Provider as an argument and several flags:

withParameters: if the flag is true, the parameters of the preferred layout instances are saved. In this case it is not necessary to use the method saveParametersToNamedProperties. Otherwise, only the name of the class of the preferred layout is saved, without its parameters. Therefore, after loading the .ivl file, the preferred layout will have, in this case, the default values for all its parameters.

withDefaults: the flag has the same meaning as for the method saveParametersToNamedProperties.

traverse: if the flag is true, the method applies recursively to the subgraphs. Otherwise, the method saves only the preferred layout of the grapher adapter on which the method is called.

The following code example shows how to save the preferred layouts to .ivl files.

IlvGrapher grapherA = new IlvGrapher();

IlvGrapher grapherB = new IlvGrapher();

// fill the graphers with nodes and links;

// grapherB is added as a subgraph of grapherA

grapherA.addNode(grapherB, false);

// Create the grapher adapter for the topmost graph

IlvGrapherAdapter adapterA = new IlvGrapherAdapter(grapherA);

// Get a grapher adapter for the subgraph

IlvGraphModel adapterB = adapterA.getGraphModel(grapherB);

// create the layout provider

IlvDefaultLayoutProvider provider = new IlvDefaultLayoutProvider();

// specify the preferred layouts for each grapher

// (this automatically attaches the layouts)

provider.setPreferredLayout(adapterA, new IlvTreeLayout());

provider.setPreferredLayout(adapterB, new IlvGridLayout());

...

// Save the settings to named properties

adapterA.savePreferredLayouts(provider, true, false, true);

// Save the nested grapher to an .ivl file

grapherA.write("abcd.ivl")

Loading layout parameters from .ivl files

The following example shows how to load and recover the parameters of the three layout instances when the layout settings are stored in an .ivl file:

// Read the IVL file. This reads all named properties as well.

grapher.read("abcd.ivl");

IlvGrapherAdapter adapter1 = (IlvGrapherAdapter)layout1.getGraphModel();

IlvGrapherAdapter adapter2 = (IlvGrapherAdapter)layout2.getGraphModel();

IlvGrapherAdapter adapter3 = (IlvGrapherAdapter)layout3.getGraphModel();

// Transfer the parameter settings from the named properties to the layouts.

adapter3.loadParametersFromNamedProperties(layout3);

adapter2.loadParametersFromNamedProperties(layout2);

adapter1.loadParametersFromNamedProperties(layout1);

// just to be sure that no named layout properties remain in the memory

adapter1.removeParametersFromNamedProperties();

adapter2.removeParametersFromNamedProperties();

adapter3.removeParametersFromNamedProperties();

When reading an .ivl file, you usually do not know how many named layout properties are stored in the file. In the previous example, if there are less than three sets of named layout properties stored in the .ivl file, any unsuccessful call of the method loadParametersFromNamedProperties has simply no effect, that is, it does not change the parameters of the corresponding layout. If there are more than three sets, the final calls of the method removeParametersFromNamedProperties guarantee that no memory is wasted by the remaining unused layout properties. As mentioned in Saving layout parameters to .ivl files, only one call to the method removeParametersFromNamedProperties is necessary if only one grapher adapter is attached to all three layout instances.

NOTE Parameters are loaded in the reverse order with respect to the order in which they are stored. This is not important if all three layout instances are of different classes because a layout automatically loads only parameters that fit the layout class. However, if, for example, all three layouts are instances of IlvTreeLayout, the last saved set of named properties for any Tree Layout is the first set of named properties that is loaded for a Tree Layout.

To load layout parameters, use one of the following methods:

loadParametersFromNamedProperties

This method transfers a set of layout parameters from the named layout properties to the input layout. It automatically determines which layout properties fit the input layout. If several sets fit, it transfers the set that was stored last, removes this set of named layout properties from the grapher, and returns true. If no set fits and loading cannot be done, it returns false.

loadParametersFromNamedProperties

This method transfers a set of layout parameters from the layout properties having the input property name to the input layout. It returns true if successful, and false otherwise.

loadParametersFromNamedProperties

This method transfers a set of layout parameters from the layout properties having the input property name to a newly created instance of IlvGraphLayout. It returns the new instance. It returns null if no set of layout properties with the input name is found.

Loading preferred layouts from .ivl files

The settings of the preferred layouts can be loaded from .ivl files using the method:

boolean loadPreferredLayoutsFromNamedProperties(IlvDefaultLayoutProvider

provider, boolean withParameters, boolean traverse);

The method takes the Layout Provider as an argument and several flags:

withParameters: if the flag is true, the parameters of the preferred layout instances are loaded. In this case it is not necessary to use the method loadParametersFromNamedProperties. Otherwise, after loading the .ivl file, the preferred layout will have, in this case, the default values for all its parameters.

traverse: if the flag is true, the method applies recursively to the subgraphs. Otherwise, the method loads only the preferred layout of the grapher adapter on which the method is called.

This method reads the named properties stored in the file and sets the preferred layout (if any has been stored) on the Layout Provider, using its method setPreferredLayout.

The following example shows how to load and recover the preferred layouts (with their parameters) when the preferred layout settings are stored in an .ivl file:

IlvGrapher grapher = new IlvGrapher();

// Create the grapher adapter for the topmost graph

IlvGrapherAdapter adapter = new IlvGrapherAdapter(grapher);

// Load the graphers from the .ivl file

grapher.read("abcd.ivl");

// Create the layout provider

IlvDefaultLayoutProvider provider = new IlvDefaultLayoutProvider();

// Load the preferred layouts into the provider

// (layout parameters are also read)

adapter.loadPreferredLayoutsFromNamedProperties(provider, true, true);

// Now the provider can be used to perform the recursive layout

adapter.performLayout(provider, true, true, true);

// Detach the layouts when the provider is no longer needed

provider.detachLayouts(adapter, true);

// Dispose the topmost adapter when no longer needed

adapter.dispose();

Additional information for expert users

Interface parameters

Some layout classes allow an interface as input parameter. For instance, the method setNodeBoxInterface sets an IlvNodeBoxInterface (see IlvLinkLayout, IlvShortLinkLayout, and so on). If an application uses a node box class that implements the node box interface, this can only be stored to an .ivl file if the node box class also implements the IlvPersistentObject interface. Otherwise, the node box class is not saved to the .ivl file.

Compatibility issues

An .ivl file that contains layout properties can be loaded only when the package ilog.views.graphlayout and its subpackages are available.

Defining your own type of layout

If you develop your own layout algorithms by subclassing IlvGraphLayout and want to save the layout parameters of your own layout algorithm in .ivl files, you should subclass IlvGraphLayoutGrapherProperty, IlvGraphLayoutNodeProperty, and IlvGraphLayoutLinkProperty, see Defining your own type of layout. You can find example code by referring to these classes in the Java™ API Reference Manual. You should also override the following methods of IlvGraphLayout to return your subclasses:

protected IlvGraphLayoutGrapherProperty createLayoutGrapherProperty(

String name, boolean withDefaults)

{

return new MyOwnLayoutGrapherProperty(name, this, withDefaults);

}

protected IlvGraphLayoutNodeProperty createLayoutNodeProperty(

String name, IlvGraphic node, boolean withDefaults)

{

return new MyOwnLayoutNodeProperty(name, this, node, withDefaults);

}

protected IlvGraphLayoutLinkProperty createLayoutLinkProperty(

String name, IlvGraphic link, boolean withDefaults)

{

return new MyOwnLayoutLinkProperty(name, this, link, withDefaults);

}

Further applications of layout properties

The layout properties can be serialized. If you prefer to use the standard serialization mechanism of Java instead of .ivl files, it is recommended to use the layout properties as well because it guarantees that only the parameters are serialized and not any temporary data that may exist in the layout instance.

The following code shows an easy way to copy the parameter setting from layout1 to layout2:

IlvGrapherAdapter adapter1 = (IlvGrapherAdapter)layout1.getGraphModel();

IlvGrapherAdapter adapter2 = (IlvGrapherAdapter)layout2.getGraphModel();

adapter1.saveParametersToNamedProperties(layout1, true);

adapter2.loadParametersFromNamedProperties(layout2);

The following code shows an easy way to undo temporary changes of layout parameters:

IlvGrapherAdapter adapter = (IlvGrapherAdapter)layout.getGraphModel();

adapter.saveParametersToNamedProperties(layout, true);

... change layout parameters

... work with changed parameters

// restore the layout parameters as they were before

adapter.loadParametersFromNamedProperties(layout);