The GraphML default extension mechanism allows to declare so-called GraphML attributes that can be used to conveniently store additional information in a GraphML file. In its original form, this mechanism directly supports additional data of type boolean, int, long, float, double, and String. By means of customization to the default mechanism, however, GraphML attributes can be used to store data of arbitrary complexity and type.

A GraphML attribute is declared using the <key> element which comprises a unique identifier as well as scope, name, and the domain of values (i.e., the actual type) for the attribute. Table 9.3, “XML attributes for GraphML <key> element” lists the set of XML attributes and describes their function within the declaration of a GraphML attribute. Note that in a GraphML file, <key> elements must be placed before any <graph> element.

Actual values for a GraphML attribute are defined using the <data> element which is nested within the GraphML elements <graph>, <node>, <edge>, or <port>. Required with each <data> element is XML attribute key which is used by a look-up mechanism to find the proper GraphML attribute declaration for the contents of a given <data> element.

This GraphML attribute look-up mechanism is responsible for matching the value given for the key attribute of a <data> element to the unique ID defined by the id attribute of a <key> element. The mapping that is established by this match is essential for delegating the parsing of a given <data> element to the proper parser code that handles the specific contents.

The GraphML default extension mechanism can be customized to enable GraphML attributes that hold arbitrarily complex data. GraphMLIOHandler uses this mechanism to read and write additional data of simple and complex type. The basic technique to enhance the extension mechanism is to define a new XML attribute with the <key> element and nest user-defined XML elements inside the <data> element.

The <key> elements define a unique id which matches the key attribute of the corresponding <data> elements. The following GraphML example has <data> elements which encode data for nodes and which are defined in the <key> element with the id "d0".

<?xml version="1.0" encoding="UTF-8"?>
<graphml xmlns="...">
...
<!-- Definition of a GraphML attribute to store additional data for a -->
<!-- graph's nodes. -->
  <key id="d0" for="node" attr.name="boolean-value" attr.type="boolean"/>

  <graph id="G" edgedefault="directed">
    ...
<!-- A node that has a <data> element referring to the GraphML attribute -->
<!-- "d0." The node's value (of type boolean) is "true." -->
    <node id="n0">
      <data key="d0">true</data>
    </node>
    <node id="n1">
      <data key="d0">false</data>
    </node>
    ...
  </graph>
</graphml>

The XML structure of the enhanced GraphML file format as defined by the yFiles GraphML engine can be seen from the following XML schema definition files:

GraphMLIOHandler delegates most of the work to a core implementation, the GraphMLHandler. That handler can be obtained using the method getGraphMLHandler(). Most aspects of GraphML reading and writing, e.g. adding attributes as shown in the next chapter, have to be configured at the core handler instead of GraphMLIOHandler itself.

GraphMLIOHandler ioh = new GraphMLIOHandler();
GraphMLHandler core = ioh.getGraphMLHandler();

Both reading and writing of additional data that is of simple types (like boolean, int, long, float, double, or String) is supported transparently. This means, an DataProvider that holds int values, for example, can be serialized to a GraphML attribute with minimal effort using the convenience functionality provided by GraphMLIOHandler (the same applies for the deserialization of a corresponding DataAcceptor).

As already mentioned above, additional data of simple type is written in a GraphML file as shown in Example 9.5, “Outline of a GraphML file with GraphML attribute of simple type”.

For data consisting of structured types, reading and writing requires a (de)serializer to be registered. Custom (de)serialization is described in the section called “Serialization and Deserialization of Structured Data”. the section called “Reading and Writing Data Using DataProviders and DataAcceptors as Data Holders” describes how the custom (de)serialization can be applied to write a complex mapped attribute. The following section handles mapped attributes of simple type.

void addInputDataAcceptor(
          String name,
          DataAcceptor dataAcceptor,
          KeyScope scope,
          KeyType type)
void addInputDataAcceptor(
          String name,
          DataAcceptor dataAcceptor,
          KeyType type)
void addInputDataAcceptor(
          String name,
          Object dataProviderKey,
          KeyScope scope,
          KeyType type)

//  <key id="d0" for="node" attr.name="boolean-value" attr.type="boolean"/>
GraphMLHandler core = ioHandler.getGraphMLHandler();
core.addInputDataAcceptor("boolean-value",
                          node2boolMap,
                          KeyScope.NODE,
                          KeyType.BOOLEAN);

Future addInputDataAcceptorFuture(
          String name,
          KeyScope scope,
          KeyType type)

void addOutputDataProvider(
          String name,
          DataProvider dataProvider,
          KeyScope scope,
          KeyType type)
void addOutputDataProvider(
          String name,
          String uri,
          DataProvider dataProvider,
          KeyScope scope,
          KeyType type)

void addRegisteredOutputDataProvider(
          String name,
          KeyScope scope,
          KeyType type)
void addRegisteredOutputDataProvider(
          String name,
          Object registryTag,
          KeyScope scope,
          KeyType type)
void addRegisteredOutputDataProvider(
          String name,
          String uri,
          Object registryTag,
          KeyScope scope,
          KeyType type)

//  <key id="d0" for="node" attr.name="boolean-value" attr.type="boolean"/>

// node2boolMap is a DataMap which implements
// both DataAcceptor and DataProvider
GraphMLHandler core = ioHandler.getGraphMLHandler();
core.addOutputDataProvider("boolean-value",
                          node2boolMap,
                          KeyScope.NODE,
                          KeyType.BOOLEAN);

The general scheme for serialization and deserialization of data types uses so-called output handlers and input handlers. These handlers are responsible for writing out, respectively reading in (structured) data. The reading and writing mechanism discussed so far uses predefined input and output handler implementations behind the scenes.

In most cases it is sufficient to rely on these implementation. However, using input and output handlers provides more flexibility in data handling like dynamic registering of such handlers: Event listener for registering both output handlers and input handlers can be attached to the GraphMLHandler using addInputHandlerProvider() and addOutputHandlerProvider() events, respectively. They are invoked by GraphMLHandler dynamically, i.e., at the time of writing or reading.

A InputHandlerProvider allows registering an input handler based on the GraphML data to parse (or to be more exact: depending on the <key> definitions). The listener has to verify whether the QueryInputHandlersEvent is not already handled and whether scope and name of the attribute match the handler's definitions. If that is the case, it registers the appropriate input handler and initializes it as shown in Example 9.14, “Attaching input handlers to a GraphMLIOHandler instance”. Registering the input handler marks the event as handled, so no other input handler will be registered for that key.

// ioHandler is of type GraphMLIOHandler
GraphMLHandler core = ioHandler.getGraphMLHandler();
core.addInputHandlerProvider(new InputHandlerProvider() {
  public void onQueryInputHandler(QueryInputHandlersEvent event)
                                      throws GraphMLParseException {
    Element keyDefinition = event.getKeyDefinition();
    // Test whether the event is not yet handled
    // and whether the key definitions are matching the handler
    if (!event.isHandled()
        && GraphMLHandler.matchesScope(keyDefinition, KeyScope.EDGE)
        && GraphMLHandler.matchesName(keyDefinition, "myEdgeAttribute")) {
      MyInputHandler handler = new MyInputHandler();
      // initialize the handler
      handler.initializeFromKeyDefinition(event.getContext(), keyDefinition);
      // register the handler
      event.addInputHandler(handler);
    }
  }
});

A OutputHandlerProvider allows registering an output handler dynamically. It is invoked each time GraphMLHandler starts a write process. An output handler can be registered as shown in Example 9.15, “Attaching output handlers to a GraphMLIOHandler instance”.

// ioHandler is of type GraphMLIOHandler
GraphMLHandler core = ioHandler.getGraphMLHandler();
core.addOutputHandlerProvider(new OutputHandlerProvider() {
  public void onQueryOutputHandler(QueryOutputHandlersEvent event)
                                        throws GraphMLWriteException {
      event.addOutputHandler(new MyOutputHandler(), KeyScope.EDGE);
  }
});

Output handlers and input handlers are implementations of interfaces OutputHandler and InputHandler, respectively. For both interfaces there are abstract implementations available which serve as convenient base classes:

The predefined classes ComplexDataProviderOutputHandler and ComplexDataAcceptorInputHandler provide the default support for writing and reading structured data that is held by DataProvider and DataAcceptor instances.

The tutorial demo application ComplexExtensionGraphMLDemo.java shows how to read and write structured data.

Adding support for custom realizer implementations to the GraphML file format can be done by registering appropriate custom serializers with the GraphMLIOHandler. GraphMLIOHandler provides a number of methods to register a RealizerSerializer:

void addNodeRealizerSerializer(NodeRealizerSerializer nrs)
void addEdgeRealizerSerializer(EdgeRealizerSerializer ers)

GraphMLIOHandler delegates the management of realizer serializers to its core Graph2DGraphMLHandler, which also offers methods to register realizer serializers. Furthermore, the realizer serializers can also be removed from the Graph2DGraphMLHandler.

void addNodeRealizerSerializer(NodeRealizerSerializer nrs)
void addEdgeRealizerSerializer(EdgeRealizerSerializer ers)

void removeNodeRealizerSerializer(NodeRealizerSerializer nrs)
void removeEdgeRealizerSerializer(EdgeRealizerSerializer ers)

The tasks of a serializer are similar to those described for serializers and deserializers in the section called “Serialization and Deserialization of Structured Data”. The encoding part of a serializer is responsible for generating any user-defined XML elements which are nested within GraphML <data> elements. The parsing part extracts its data by processing the DOM (Document Object Model) structure of a GraphML file starting at the DOM node that represents a GraphML <data> elements.

It is recommended to use the abstract classes AbstractNodeRealizerSerializer and AbstractEdgeRealizerSerializer as base for custom realizer serializers. These classes already handle the (usually) common tasks like reading and writing labels or the geometry.

A node or edge realizer serializer which is based on the abstract classes has to implement the following methods:

Tutorial demo application CustomNodeRealizerSerializerDemo.java, which uses CustomNodeRealizerSerializer.java, shows the code of a custom realizer serializer, how it is registered with the RealizerSerializerManager of a GraphMLIOHandler instance, and also how it is used.

A GenericNodeRealizer or GenericEdgeRealizer is serialized automatically by writing out its configuration name. See the section called “Providing Interface Implementations” for details about customizing a generic node or edge realizer. The example configuration in that chapter which is registered with the name "Ellipse" will be serialized as <y:GenericNode configuration="Ellipse">.

When reading GraphML developers have to make sure that a generic node or edge realizer configuration with the serialized configuration name exists. If not a configuration with that name will be created using the default implementations.

The style properties and user data associated with the realizer will be (de)serialized automatically. Simple types will be (de)serialized without further configuration. For complex types, a matching SerializationHandler and DeserializationHandler have to be registered at the GraphMLHandler as described in the section called “Serialization and Deserialization of Structured Data”.

The yFiles GraphML engine provides advanced conversion services for arbitrary XML-based data. By means of a suitable XSLT stylesheet any valid XML file can be transformed into a graph structure encoded in GraphML file format.

The tutorial demo application XmlXslDemo.java shows how to import XML files as GraphML. Predefined XSLT stylesheets are available for the following XML-based file types and information:

The most convenient way to use the yFiles GraphML engine for reading and writing GraphML file format is by using the services of class GraphMLIOHandler. However, being a true yFiles IOHandler, this class requires a Graph2D object when reading or writing a file. Using the class GraphMLHandler it is also possible to read and write graphs of arbitrary type.