| Roundtrip Support Classes | ||
|---|---|---|
| Prev | Chapter 7. yFiles FLEX Java Server API | Next |
Similar to class RoundtripHandler in the yFiles FLEX client API, the Java server API provides class
GraphRoundtripSupport
. This class
makes it easy to deserialize GraphML
data that was sent from the client and to send a serialized graph instance back
to the client.
Before a response is sent, any kind of modification can be
applied to the graph using the yFiles Java API.
If the native yFiles FLEX GraphML extension is used for client-server communication (recommended),
a LayoutGraph instance should be used
as the graph model on the server.
To create and configure a LayoutGraph instance and to (de)serialize the LayoutGraph
instance to/from GraphML data, the server library offers class
GraphRoundtripSupport.
It is the server side counterpart of the client side RoundtripHandler.
The basic methods of the roundtrip support classes for deserializing GraphML data sent from the client into a Graph instance and for sending the serialized Graph instance back to the client are listed below:
| Methods for populating a graph | |
| API | void readGraph(InputStream is, Graph graph) throws IOException |
| Description | Populate the given graph using the GraphML data passed as InputStream or as parameter of the given request, respectively. |
| Methods for writing a graph | |
| API | void sendGraph(Graph graph, OutputStream os, String outputEncoding) throws IOException |
| Description | Send the given graph instance as GraphML data using the given output stream or response. |
Custom graph item attributes can be easily added for (de)serialization using
addMappper()
as shown below. Alternatively, all attributes in the GraphML can be read by enabling
setAutoReadMapperData(boolean).
DataProviders which are read using the auto read feature will be written automatically if
setAutoWriteMapperData is set to true. Adding custom graph item attributes for client-server
roundtrips is discussed
in detail in the corresponding knowledge base article.
void addMapper(Object tag, String name, KeyType valueType, KeyScope scope) |
|
| Description | Adds a simple attribute. |
void setAutoReadMapperData(boolean autoReadMapperData) |
|
| Description | Whether to automatically read and write mapped data. |
The following methods
can be used to create and configure the graph instance that is populated
with the graph structure received from the client. The created graph can safely be cast into a
StyledLayoutGraph.
public LayoutGraph createRoundtripGraph() |
|
| Description | Create the graph instance |
protected void configureRoundtripGraph( LayoutGraph layoutGraph ) |
|
| Description | Configure the graph instance, e.g. by adding custom DataProviders. |
Proper IDs are needed for client-server communication so the client graph can
be incrementally updated and the server knows which graph items to act upon.
If
createRoundtripGraph()
is used for creating graph instances on the server, the roundtrip support
registers DataMaps for node and edge IDs with the graph. These maps can be obtained using
y.base.Graph.getDataProvider() with the keys AbstractGraphRoundtripSupport.NODE_2_ID_DPKEY and
AbstractGraphRoundtripSupport.EDGE_2_ID_DPKEY.
More information about handling IDs can be found in a knowledge base
article about this topic.
The roundtrip support classes can also be used to send XML formatted error messages to the client:
| Sending error messages | |
| API | public void sendError(Throwable e, ServletOutputStream outputStream) throws IOException |
| Description | Send an Exception's message or a custom error message to the client. |
The XML data sent to the client can be handled on the client as described in the section called “Handling Custom Errors” and is formatted as follows:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<errors>
<error>
error message
<error>
</errors>
</response>
GraphML serialization and deserialization of Graph instances can be controlled by overriding the protected methods of GraphRoundtripSupport listed below:
protected void configureHandler(GraphMLLayoutGraphIOHandler layoutGraphIOHandler) |
|
| Description | Configure the I/O handler for reading and writing Graph instances |
protected GraphMLLayoutGraphIOHandler createHandler() |
|
| Description | Create the I/O handler instance for reading and writing graph instances. |
protected void addRegisteredHandlers(GraphMLHandler handler) |
|
| Description | Add all SerializationHandler and DeserializationHandler used for reading and writing the graph to the GraphMLHandler. This method can be overridden in order to register custom SerializationHandler and DeserializationHandler instances. |
The GraphRoundtripSupport option for automatic label model conversion is shown below. If setMapLabelModels is set to true, the I/O mechanism will try to convert between the client and yFiles Java label models. For edge labels, the conversion is possible for the slider- and free label models. Node label position can be mapped if the discrete node label model is used (exterior or interior node label model on the client).
void setMapLabelModels( boolean mapLabelModels ) |
|
| Description | Set whether client label models should be mapped to yFiles Java label models in order to transfer label positions in a client-server roundtrip. |
The yFiles Java label position information will be committed to the label model parameters of yFiles FLEX client
Label instances when the graph is written back to the client.
The position information can also be committed before, using the static method
FlexIOTools.copyLabelLayouts(LayoutGraph graph).
As discussed in Chapter 6, Using yFiles FLEX with a yFiles Server, the yFiles FLEX client can communicate with a yFiles Java server either using the yFiles FLEX native GraphML extension or using a compatibility mode for the yFiles Java GraphML format.
If the yFiles Java GraphML extension is chosen for client-server communication, a
a Graph2D instance will be used on the server
to create and modifiy the graph structure and graph visualization information.
Class
Graph2DRoundtripSupport
conveniently creates and configures a Graph2D instance for this purpose.
Similar to GraphRoundtripSupport the graph instance used for roundtripping should be created by
createRoundtripGraph().
The created graph can safely be cast into a Graph2D.
public LayoutGraph createRoundtripGraph() |
|
| Description | Create the graph instance |
protected void configureRoundtripGraph( LayoutGraph layoutGraph ) |
|
| Description | Configure the graph instance, e.g. by adding custom DataProviders. |
GraphML serialization and deserialization of Graph2D instances can be controlled by overriding the protected methods of Graph2DRoundtripSupport listed below:
protected void configureHandler(Graph2DGraphMLHandler ioHandler) |
|
| Description | Configure the I/O handler for reading and writing Graph2D instances. |
protected Graph2DGraphMLHandler createHandler() |
|
| Description | Create the I/O handler instance for reading and writing Graph2D instances. |
Both roundtrip support classes have base classes which can be used in environments where a servlet API
is not available:
GraphRoundtripSupportBase
or class Graph2DRoundtripSupportBase
These classes provide the same functionality as GraphRoundtripSupport and Graph2DRoundtripSupport, except that reading from a request and writing or sending errors to a response is not supported. The supported methods for reading, writing, and error handling are:
void readGraph(InputStream is, Graph graph) throws IOException |
|
| Description | Populate the given graph using the GraphML data passed as InputStream. |
void sendGraph(Graph graph, OutputStream os, String outputEncoding) throws IOException |
|
| Description | Send the given graph instance as GraphML data using the given output stream. |
public void sendError(Throwable e, ServletOutputStream outputStream) throws IOException |
|
| Description | Send an Exception's message to an output stream. |
|
Copyright ©2007-2015, yWorks GmbH. All rights reserved. |
