If the send property is true, the graph instance currently displayed in the GraphCanvasComponent that was passed to the RoundtripHandler will be serialized to a GraphML string and transferred to the server. The data send to the server and the graph serialization process can be easily configured using the following methods and properties:

sendOptions:uint

additionalParameters:Object

addSerializer(serializer:ISerializer):void

outputIOHandler:GraphMLIOHandler

Additional GET or POST parameters to be sent to the server can be added using the additionalParameter property like shown in Example 5.1, “Using additional POST/GET parameters”. The exampe code will add the parameters "name1" and "name2" with the values "value1" and "value2", respectively.

Note that the following parameter names are reserved for internal use: graph, graphEncoding, and encodeURIComponent.

// adding POST or GET parameters
// results in a request like
// http://foo.bar.com/serviceName?name1=value1&name2=value2
var params:Object = new Object();
params.name1 = "value1";
params.name2 = "value2";
roundtripHandler.additionalParameters = params;

The sendOptions define which data will be sent in the GraphML in addition to the structure and layout information. The options are defined in the OPTION_COPY constants of GraphCanvasComponent and can be combined by bitwise OR. The OPTION_COPY constants are listed in Table 5.1, “Constants to be used with updateOptions and sendOptions”.

If the update property is true, the current graph instance will be updated using the deserialized GraphML data contained in the server response. Deserialization and the update process can be configured using the following properties and methods:

updateOptions:uint

addDeserializer(deserializer:IDeserializer):void

inputIOHandler:GraphMLIOHandler

animate:Boolean

The updateOptions define which data will be updated in the GraphML in addition to the structure and layout information. The options are defined in the OPTION_COPY constants of GraphCanvasComponent and can be combined by bitwise OR. The OPTION_COPY constants are listed in Table 5.1, “Constants to be used with updateOptions and sendOptions”.

Folded graph (See also Chapter 3, Graph Hierarchies) can contain more states than visible in the current graph, contents of a closed group node, for instance. Generally, there are two ways to send a folded graph to the client: Sending the folder nodes as folders together with their nested graphs (the folder contents) or sending the closed folder nodes as "normal" nodes. The first case is the RoundtripHandler's default. For some use cases, e.g. layout roundtrips, on might want to send only the currently visible state (the second case). This can be achieved by setting RoundtripHandler's localViewMode to true.

localViewMode:Boolean

Additional mapped data (see also the section called “Mapping Data to Graph Elements”) can also be transferred by the RoundtripHandler. However, the RoundtripHandler has to be made aware of the existence of the mapped data. The RoundtripHandler method addMapperAttribute() allows to add custom graph item attributes which will be considered for both communication directions:

function addMapperAttribute(tag:Object,
        name:String = null,
        scope:String = GraphMLConstants.SCOPE_NODE,
        contentType:String = GraphMLConstants.TYPE_STRING):void

Alternatively, IMapper's default implementation, DictionaryMapper can be configured to be automatically transferred by the RoundtripHandler. To support this feature the RoundtripHandler's autoWriteMapperData and/or autoReadMapperData properties have to be enabled (which they are by default).

function DictionaryMapper(
        weakKeys:Boolean=false,
        name:String=null,
        scope:String=null,
        valueType:String=null,
        autoSerialize:Boolean=false )

autoWriteMapperData:Boolean
autoReadMapperData:Boolean

The following example shows how to set up a mapper for automatic transfer:

// set up the mapper to be auto-serialized with the name "my-map",
// the contents are of the type String and the mapper is bound to nodes
var map:IMapper = new DictionaryMapper(true, "my-map", GraphMLConstants.SCOPE_NODE, GraphMLConstants.TYPE_STRING, true);
// graph is of type IGraph
graph.mapperRegistry.addMapper("my-map", map);

// set up the handler.
// handler is of type RoundtripHandler
// to transfer node data, the options have to be
// at least GraphCanvasComponent.OPTION_COPY_NODE_DATA
handler.sendOptions = GraphCanvasComponent.OPTION_COPY_ALL;
handler.updateOptions = GraphCanvasComponent.OPTION_COPY_ALL;
// enable auto (de)serialization
handler.autoReadMapperData = true;
handler.autoWriteMapperData = true;

Detailed information about how to enable client-server roundtripping of custom graph item attributes can be found in a knowledge base article about this topic.

User tags (see also the section called “User Tags”) are automatically transferred if the sendOptions and/or updateOptions are set to transfer user tags (see also Table 5.1, “Constants to be used with updateOptions and sendOptions”).

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. These IDs are stored in IMappers which are always registered with DefaultGraph's mapper registry. The mappers can be obtained using the keys DefaultGraph.MAPPER_KEY_NODE_2_ID and DefaultGraph.MAPPER_KEY_EDGE_2_ID. More information about handling IDs can be found in a knowledge base article about this topic.

Class RoundtripHandler allows to customize error handling for any errors that might occur during client-server communication. Error handling can be configured both globally and for single RoundtripHandler instances. The properties of class RoundtripHandler that allow to register custom error handling delegates are listed below:

[static] globalFaultEventHandler:Function

[static] globalCustomErrorHandler:Function

faultEventHandler:Function

customErrorHandler:Function

/**
 * Custom fault handler that displays the error message in an alert popup.
 */ 
private function faultHandler( evt:FaultEvent ):void {
    var titleString:String = "Service request failed";
    var buf:String = "Error details: \n\n";
    buf += evt.fault.faultDetail;
    Alert.show( buf, titleString );
    CursorManager.removeBusyCursor();
}

private function init():void {
    // register the custom fault handler
    RoundtripHandler.globalFaultEventHandler = faultHandler;
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <errors>
    <error>
      message
    <error>
  </errors>
</response>

private function handleCustomError( evt:ResultEvent ):void {
    var xml:XML = XML( evt.result );
    var errors:XMLList = xml.errors;
    if( errors.length() > 0 ) {
        Alert.show( "ERROR: \n"+errors.error[ 0 ].toString() );
        for each( var error:XML in errors.children() ) {
                trace(error.toString());
        }
        // prevent any further processing of the result event.
        evt.stopImmediatePropagation();
        CursorManager.removeBusyCursor();
        Application.application.enabled = true;
    }
}

Class RoundtripHandler offers two properties that influence the format that is used for transferring the GraphML serialization of the client graph to the server:

compress:Boolean

uriEncode:Boolean

The default value of the compress property is true, because the compression will speed up the client-server communication substantially. Both the Java and .NET server libraries are able to handle zlib-compressed graphs sent from the client. The uriEncode property should only be enabled when compression is disabled. URI-encoding ensures the correct transfer of special characters if compression is turned off. If compression is turned on, the compressed bytes will be transfered as a Base64-encoded string.

For most scenarious, a configured RoundtripHandler will suffice for general server communication in a yFiles FLEX application. If the various public properties and methods provided by class RoundtripHandler do not allow enough flexibility, protected methods are provided that can be overriden for further customization:

createAction():ServerAction

createOutputIOHandler():GraphMLIOHandler
createInputIOHandler():GraphMLIOHandler

doUpdate(newGraph:IGraph):void

createParameters():Object

Example 5.5, “Custom style round-trip” shows an example usage of class RoundtripHandler. The handler is configured such that a custom node style and a custom node attribute is transferred to the server. The server may modify the node attribute, the properties of the custom style, the graph structure, and/or the graph layout. After the server response has been deserialized, these modifications will be reflected in the graph instance currently displayed in the graph canvas that was passed to the RoundtripHandler constructor. Note that the ISerializer instance that serializes the custom node style will be retrieved by the GraphML framework from the custom style renderer through the look-up mechanism.

private static const CUSTOM_NODE_ATTRIBUTE:String = "customNodeAttribute";

// Create a round-trip handler for a GraphCanvasComponent instance.
// The handler will call a service called "customStyleRoundtrip".
roundtripHandler = new RoundtripHandler(graphCanvas, "customStyleRoundtrip");
// Add a custom style deserializer that will be used for deserialization of the
// server response.
roundtripHandler.addDeserializer(CustomStyleDeserializer.instance);
// Add a custom node attribute that will be serialized and deserialized.
roundtripHandler.addMapperAttribute(
  CUSTOM_NODE_ATTRIBUTE, CUSTOM_NODE_ATTRIBUTE, GraphMLConstants.SCOPE_NODE);
roundtripHandler.run();

The DownloadHandler delegates the serialization process to a GraphMLIOHandler. By default, this handler is created by the protected method createOutputIOHandler(). It is possible to customize the DownloadHandler (e.g. adding mapper attributes or using a JavaCompatGraphMLIOHandler) by replacing this output handler.

There are two ways to set a customized output handler: passing a RoundtripHandler instance as the constructor's optional parameter roundtripHandler or setting a GraphMLIOHandler instance to the outputIOHandler property. The RoundtripHandler can be configured as shown above in the section called “Class RoundtripHandler”. It is possible and convenient to use the same RoundtripHandler instance as used for roundtripping.

DownloadHandler(downloadURL:String, roundtripHandler:RoundtripHandler = null)

outputIOHandler:GraphMLIOHandler

For common file download requests, class DownloadHandler can be used directly. Nevertheless, if custom event handling of download requests is needed, the DownloadHandler offers event listeners for all events that may occur during a download request may be overriden.

Class UploadHandler offers various methods and properties for configuring the upload and deserialization process of the GraphML file:

additionalParameters:Object

inputIOHandler:GraphMLIOHandler

roundtripHandler:RoundtripHandler

fileFilter:Array