Table of Contents
This chapter explains the formats that are used for communication and file I/O in yFiles applications.
All yFiles libraries use the GraphML format to read and write graph structures and visual attributes of graph items. How to work with yFiles FLEX and the respective GraphML extensions of yFiles Java and yFiles.NET is explained in the sections dealing with the corresponding server technology:
For details on the specific server APIs, see the corresponding chapters, Chapter 6, yFiles FLEX Java Server API and Chapter 7, yFiles FLEX .NET Server API.
The architecture used by yFiles Java for defining and rendering the visual representation of graph items differs from the architecture used in yFiles FLEX.
yFiles Java uses so-called "realizers" to draw nodes and edges. A realizer contains all properties that are necessary to draw the visual representation of a graph item as well as the code that performs the actual painting. Node realizers and edge realizers also draw the labels assigned to a node or edge. In contrast, in yFiles FLEX a "style" defines the visual properties of a node, an edge, or a label. The drawing code is contained in a separate renderer implementation that knows how to draw a specific style. Also, the location and size of a node (its "layout") is part of the node itself in yFiles FLEX. In yFiles Java, the node layout is a property of the node's realizer.
Because of these architectural differences, the native GraphML format of yFiles FLEX and yFiles Java differs. Example 5.1, “GraphML Format Comparison” compares a labeled node's GraphML serialization using both products.
Example 5.1. GraphML Format Comparison
| yFiles FLEX GraphML format | yFiles Java GraphML format |
|---|---|
| The yFiles FLEX GraphML extensions serialize style, labels, and geometry using separate data elements. | The serialization of a yFiles Java shape node contains all graphical information for the node as well as the label visualization properties and the node geometry. |
<node id="n0_OLD">
<data key="d8">
<y:IShapeNodeStyle>
<y:Shape>Rectangle</y:Shape>
<y:Pen name="SolidColor" color="Black" width="1"/>
<y:Brush name="SolidBrush" color="#ffffcc00"/>
</y:IShapeNodeStyle>
</data>
<data key="d9">
<y:Labels>
<y:Label>
<y:ISimpleLabelStyle>
<y:Font family="Serif" points="12" style="Regular"/>
<y:Brush name="SolidBrush" color="Black"/>
</y:ISimpleLabelStyle>
<y:InteriorLabelModel position="Center">
<y:ModelState>
<y:Insets left="0" right="0" top="0" bottom="0"/>
</y:ModelState>
</y:InteriorLabelModel>
<y:Text>A Label</y:Text>
<y:PreferredSize width="46" height="19"/>
</y:Label>
</y:Labels>
</data>
<data key="d10">
<y:Geometry x="281" y="341" width="30" height="30"/>
</data>
</node> |
<node id="n0_OLD">
<data key="d1">
<y:ShapeNode>
<y:Geometry x="281" y="341" width="30" height="30"/>
<y:NodeLabel modelName="internal" modelPosition="c" x="-23" y="9.5"
width="46" height="19" fontFamily="Serif" fontSize="12"
fontStyle="plain" textColor="#000000">A Label</y:NodeLabel>
<y:Shape type="rectangle"/>
<y:Fill color="#ffcc00" transparent="false"/>
<y:BorderStyle color="#000000" type="line" width="1"/>
</y:ShapeNode>
</data>
</node> |
As shown in Figure 5.1, “GraphML extensions for communication with a yFiles for Java server”, both GraphML extensions can be used for communication between a yFiles FLEX client and a yFiles Java server. The necessary configuration steps as well as the shortcomings and benefits of both approaches will be described below.
To find out how to work with yFiles FLEX and either of the two GraphML extensions, please see the corresponding section:
For most yFiles FLEX applications using a yFiles Java server component, it is recommended to use the native GraphML extension of yFiles FLEX.
In general, the native yFiles GraphML extension should be used, if:
- the server is only used for running automatic graph layouts and there is no need to change the visual appearance of graph items on the server.
- the server only changes the graph's structure.
- the server has to alter the visual properties of graph items, but the default realizer implementations offered by yFiles Java will not suffice to render all graphical properties required by the application.
- custom styles are used on the client.
- all visual properties can be deduced from model properties determined by the server (e.g. if the "expandable" attribute of a node is set, draw an "expand"-button on top of the node)
- memory consumption is an issue on the server. When using the yFiles FLEX GraphML extension, no realizer objects are created on the server for parsed nodes.
To use the native GraphML extension of yFiles FLEX, no special configuration is needed on the client. A plain RoundtripHandler can be used for communication with the server. If only geometric and structural information has to be transferred between client and server, not much configuration has to be done on the server, either (see the section called “Transferring Only Structural and Layout Information” for information on how to disable the transfer of style information).
If a yFiles Java server has to access and/or modify the style information, it will use org.w3c.dom.DocumentFragments for this purpose. Section "Manipulating yFiles FLEX GraphML Style Data" describes how to access the serialized style information of the yFiles FLEX client in a yFiles Java server.
Note
If the serialized style information will be accessed or modified on the server, the writeSharedReferences
property of the I/O handler that is used for serialization on the client should be
set to false.
Note that the document fragments will only be read and written automatically on
the server, if a
GraphRoundtripSupport
is used for reading and writing on the server.
The custom style demo application that is included in the yFiles FLEX distribution demonstrates how to manipulate a custom yFiles FLEX style with yFiles Java.
Although it is usually recommended to use the native yFiles FLEX GraphML extension in a yFiles FLEX application, it is advisable for some usecases to use the yFiles Java GraphML extension instead. It is recommended to use the yFiles Java GraphML format, if:
- all visual properties of graph items that are required by the application are provided by the default yFiles Java realizers.
- an existing yFiles Java application that makes use of the different visual properties provided by the default yFiles Java realizers or that contains custom realizer implementations is migrated to yFiles FLEX.
If the yFiles Java GraphML format is chosen for a yFiles FLEX application because the visual properties offered by the default yFiles Java realizers seem sufficient, note that once any additional visual properties are required for the application that are not supported by the default realizers, it will be harder to implement these additional properties using this approach.
No matter which server technology is used, it will be easier to add custom visual appearances to a yFiles FLEX application if the yFiles FLEX native GraphML format is used instead of the yFiles Java GraphML extension. However, if the Java application uses only the default realizer implementations provided by yFiles for Java or if the (de)serialization for custom realizers has already been implemented using custom realizer serializers, using the yFiles for Java compatibility features of yFiles FLEX allows to migrate the graphical appearance of the diagrams to the client without much effort.
The JavaCompatDemo included in the yFiles FLEX distribution shows how a Graph2D instance that uses arbitrarily configured default and custom yFiles for Java realizers can be displayed with a yFiles FLEX client.
To enable reading and writing of the yFiles Java GraphML extension,
class JavaCompatGraphMLIOHandler
is used. Please see
API Excerpt 3.3, “Using a GraphMLIOHandler for reading and writing yFiles Java GraphML data” for details on using
JavaCompatGraphMLIOHandler.
Table 5.1, “yFiles Java compatibility styles” lists the mapping from yFiles Java realizers to yFiles FLEX compatibility styles. If a yFiles Java realizer is parsed on the client, the corresponding compatibility style listed in the table will be created.
Table 5.1. yFiles Java compatibility styles
| yFiles Java realizer | yFiles Flex style |
|---|---|
| ShapeNodeRealizer |
JavaShapeNodeStyle
/JavaShapeNodeStyleRenderer |
| ImageNodeRealizer |
JavaImageNodeStyle
/JavaImageNodeStyleRenderer |
| PolyLineEdgeRealizer |
PolylineEdgeStyle
/PolylineEdgeStyleRenderer |
The client library's AbstractJavaNodeStyle
corresponds to the abstract NodeRealizer
in yFiles Java.