Package y.io provides the necessary functionality for both reading and writing graph structure data from and to a file, respectively. All of the classes that implement input/output functionality work on an instance of type Graph2D. As a consequence, writing out a graph is not restricted to the graph structure itself, but also supports the complete set of visual attributes, i.e., in particular, everything related to the visual representation of graph elements.

Directly supported file formats are GraphML, GML, XGML, TGF, and YGF for graph exchange, and GIF and JPG for graph export (image export). Extension packages provide further file formats like SVG, PDF, EMF, SWF, and EPS for graph export (vector graphics export). Via the Java Image I/O API (package javax.imageio, available with Java 2 Standard Edition version 1.4 and higher) additional file formats for graph export, for example PNG, are also accessible. Table 9.1, “Graph exchange and export file formats” lists the features of all yFiles graph exchange and export file formats.

The graph exchange formats mainly concentrate on the graph structure, which also includes nested graph structure. They do not support visual aspects that are not associated with the graph, like, e.g., zoom level, selection state, or a background image. In contrast, the graph export formats fully support these visual aspects.

The graph exchange formats (except TGF) do, however, support all visual attributes that are directly related to the representation of graph elements. First and foremost, this means that most of the information encoded by classes NodeRealizer and EdgeRealizer is written to/read from file.

Reading and writing graph structures from/to file is decribed in Reading and Writing Graph Structure Data, the section Exporting a Graph's Visual Representation explains image export of a graph's visual representation.

Input/Output Handlers

Common to reading/writing of all file formats is the use of so-called input/output handlers, i.e., subclasses of abstract class IOHandler. The hierarchy of these input/output handlers is shown in Figure 9.1, “The class hierarchy in package y.io”. Observe that the subclasses on the right side provide only for image export facilities, i.e., output of a graph's visual representation, while those on the left side provide for true graph structure exchange, i.e., input and output.

Figure 9.1. The class hierarchy in package y.io

Note

To stay consistent with the naming scheme the classes GIFIOHandler and JPGIOHandler should have been named GIFOutputHandler and JPGOutputHandler, respectively.

Abstract class IOHandler provides the basic mechanism to read/write a graph from/to a file. This mechanism comprises methods to read a graph from a stream and to write a graph to a stream, respectively. Also included are getter methods for a format-specific descriptive string and file name extension. The four most essential methods are all defined abstract, so descendants of class IOHandler have to implement them appropriately:

abstract void read(Graph2D graph, InputStream in) abstract void write(Graph2D graph, OutputStream out) abstract String getFileFormatString() abstract String getFileNameExtension()
Description	Abstract methods from class IOHandler.

A subclass that implements only output functionality has to override the IOHandler.read(Graph2D, InputStream) method with an empty body. Additionally, it should provide its own canRead() method which should always return false.

Note

By default, the methods canRead(), canWrite(), and canWriteSubset() from abstract class IOHandler all return true.

The source code in Example 9.1, “Using getter methods from class IOHandler” shows how getter methods defined in class IOHandler can be used to quickly match file formats to their respective input/output handler implementations and also shows how to build a list holding the descriptive strings for supported file formats.

Example 9.1. Using getter methods from class IOHandler

// 'ioHandlers' is of type java.util.Collection. 

IOHandler getIOHandler(String fileName)
{
  Iterator iter = ioHandlers.iterator();
  while (iter.hasNext())
  {
    IOHandler ioh = (IOHandler)iter.next();
    // Test if the given string ends with the specific file name extension of 
    // any of the registered input/output handlers on the list. 
    if (fileName.endsWith(ioh.getFileNameExtension()))
      return ioh;
  }
  // No matching input/output handler has been found. 
  return null;
}

Collection makeIOHandlerDescription()
{
  Collection descrList = new Vector();
  
  Iterator iter = ioHandlers.iterator();
  while (iter.hasNext())
  {
    IOHandler ioh = (IOHandler)iter.next();
    // For every registered input/output handler on the list add its 
    // descriptive format string. 
    descrList.add(ioh.getFileFormatString());
  }
  // Return the description list. 
  return descrList;
}

Both reading a graph from and writing a graph to a file is actually done with only few lines of source code. Example 9.2, “Reading and writing a graph structure from/to file” shows two methods that can be used in conjunction with any descendant of class IOHandler.

Example 9.2. Reading and writing a graph structure from/to file

void readGraphFromFile(Graph2D graph, IOHandler ioh, String inFile)
{
  try {
    // Reading in the graph using the given IOHandler. 
    ioh.read(graph, inFile);
  }
  catch (IOException ioEx) {
    // Something went wrong. Complain. 
    printErrorMessage("Cannot read graph from file '" + inFile + "'.");
  }
}

void writeGraphToFile(Graph2D graph, IOHandler ioh, String outFile)
{
  try {
    // Writing out the graph using the given IOHandler. 
    ioh.write(graph, outFile);
  }
  catch (IOException ioEx) {
    // Something went wrong. Complain. 
    printErrorMessage("Cannot write graph to file '" + outFile + "'.");
  }
}