Remote API

Remote API
Prev	Chapter 4. Communicating with the Server	Next

Package com.yworks.remote provides classes and interfaces that facilitate communication with HTTP services.

Class RoundtripHandler

The central class that offers easy-to-use server round-tripping support is the RoundtripHandler. The round-trip handler can be used both for stateless and stateful web applications and provides server response handling as well as various properties and methods that influence the data that is transferred to the server.

Class RoundtripHandler can be used for complete server round-trips and one-way data transfers (e.g. loading a graph from the server or saving a graph on the server). API Excerpt 4.1, “RoundtripHandler transfer direction properties” lists the RoundtripHandler properties that configure transfer directions.

API Excerpt 4.1. RoundtripHandler transfer direction properties

// Get and set whether to transfer the serialized graph instance to the server.
function get send():Boolean
function set send(send:Boolean):void

// Get and set whether to update the current graph instance by deserializing 
// the GraphML data received from the server.
function get update():Boolean
function set update(update:Boolean):void

API Excerpt 4.2, “Adding graph item attributes to a RoundtripHandler” describes the RoundtripHandler method addMapperAttribute that allows to add custom graph item attributes which will be considered for both communication directions.

API Excerpt 4.2. Adding graph item attributes to a RoundtripHandler

// Add a graph item attribute with the given attribute name for input and 
// output.
// An IMapper instance has to be registered with the current graph's mapper 
// registry for the given tag.
function addMapperAttribute(tag:Object, name:String = null, 
                            scope:String = GraphMLConstants.SCOPE_NODE, 
                            contentType:String = 
                              GraphMLConstants.TYPE_STRING):void

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.

Customizing Graph Serialization

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 methods listed in API Excerpt 4.3, “RoundtripHandler send configuration”. Note that there is no convenience method for registration of custom ISerializer implementations on RoundtripHandler, because ISerializer implementatios will be retrieved using the lookup mechanism of model items. However, serializers can also be registered directly on the GraphMLIOHandler instance used by the RoundtripHandler. See the section called “General Serializer and Deserializer Concepts” for details on customizing GraphML serialization.

API Excerpt 4.3. RoundtripHandler send configuration

// Get and set an object containing additional GET or POST parameters that will 
// be transferred to the server.
function get additionalParameters():Object
function set additionalParameters(additionalParameters:Object):void

// Get and set options specifying the graph item data that will be 
// transferred to the server. The options are given as a combination of 
// OPTION_COPY constants defined in GraphCanvasComponent.
function get sendOptions():uint
function set sendOptions(sendOptions:uint):void

// Get and set the GraphMLIOHandler that will be used for graph serialization.
// A custom set of GraphML output handlers can be used for serialization by 
// either setting a configured GraphMLIOHandler or by adding/removing output 
// handlers to/from the GraphMLIOHandler instance used by the RoundtripHandler.
function get outputIOHandler():GraphMLIOHandler
function set outputIOHandler(outputIOHandler:GraphMLIOHandler):void

Customizing Graph Deserialization and Update

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 properties and methods listed in API Excerpt 4.4, “RoundtripHandler update configuration”.

API Excerpt 4.4. RoundtripHandler update configuration

// Get and set options specifiying the graph item data that will be updated 
// from the deserialized server response.
// The options are given as a combination of OPTION_COPY constants defined in 
// GraphCanvasComponent.
function get updateOptions():uint
function set updateOptions(sendOptions:uint):void

// Get and set the GraphMLIOHandler that will be used for graph deserialization.
// A custom set of GraphML input handlers can be used for deserialization by 
// either setting a configured GraphMLIOHandler or by adding/removing input 
// handlers to/from the GraphMLIOHandler instance used by the RoundtripHandler.
function get inputIOHandler():GraphMLIOHandler
function set inputIOHandler(inputIOHandler:GraphMLIOHandler):void

// Add a deserializer that will be used by the input GraphMLIOHandler.
function addDeserializer(deserializer: IDeserializer):void

// Get and set whether the optional update of the graph instance should be 
// visualized as an animation.
function get animate():Boolean
function set animate(animate:Boolean):void

RoundtripHandler events

Encoding GraphML Data

Class RoundtripHandler offers two properties that influence the format that is used for transferring the GraphML serialization of the client graph to the server. These methods are listed in API Excerpt 4.5, “Encoding methods of class RoundtripHandler”.

API Excerpt 4.5. Encoding methods of class RoundtripHandler

// Get/set whether zlib-compression is applied to the GraphML string.
function get compress():Boolean
function set compress(value:Boolean):void

// Get/set whether the encodeURIComponent function is applied to the GraphML 
// string.
function get uriEncode():Boolean
function set uriEncode(value:Boolean):void

The compress is enabled per default, 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.

Subclassing RoundtripHandler

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. These methods are listed in API Excerpt 4.6, “Protected methods of class RoundtripHandler”.

API Excerpt 4.6. Protected methods of class RoundtripHandler

// Create the ServerAction that specifies the request properties and the HTTP 
// service URL that will be used by this ResultHandler.
function createAction():ServerAction

// Create and configure the GraphMLIOHandler instance that will be used for 
// graph serialization and deserialzation, respectively.
function createOuputIOHandler():GraphMLIOHandler
function createInputIOHandler():GraphMLIOHandler

// Create the graph instance that will be populated upon deserialization of the 
// server response.
function createGraph():IGraph 

// Performs the update of the current graph instance using the graph instance 
// that was populated upon deserilaization of the server response.
function doUpdate(newGraph:IGraph):void

// Create the object containing all parameters that will be send to the server.
function createParameters():Object

Using RoundtripHandler

Example 4.1, “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.

Example 4.1. Custom style round-trip

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();

Class DownloadHandler

The yFiles FLEX remote API offers a class tailored for server requests that are expected to be responded with a file stream which is to be saved locally.

The DownloadHandler sends a serialized graph to the server and shows a download dialog that allows the user to select a download destination. The serialized graph that is send in response for local storage may of course differ from the data that was send to the server. Example 4.2, “Using DownloadHandler” shows a basic usage example of class DownloadHandler.

Example 4.2. Using DownloadHandler

// The service URL that responds with a file transfer.
var serviceURL = "http://localhost:8080/download";

// Create a DownloadHandler for the service URL.
var downloadHandler:DownloadHandler = new DownloadHandler(serviceURL);

// Trigger file download.
// 'graphCanvas' is of type com.yworks.ui.GraphCanvasComponent.
downloadHandler.download(graphCanvas.graph, "theGraph.graphml");

Configuring DownloadHandler

Similar to class RoundtripHandler, DownloadHandler offers various methods and properties for configuring the serialization process. API Excerpt 4.7, “DownloadHandler serialization configuration” lists these configuration possibilities.

API Excerpt 4.7. DownloadHandler serialization configuration

// Get and set an object containing additional GET or POST parameters that will 
// be transferred to the server.
function get additionalParameters():Object
function set additionalParameters(additionalParameters:Object):void

// Add a graph item attribute with the given attribute name for input and 
// output.
// An IMapper instance has to be registered with the graph's mapper registry 
// for the given tag.
function addMapperAttribute(tag:Object, name:String = null, 
                            scope:String = GraphMLConstants.SCOPE_NODE, 
                            contentType:String = 
                              GraphMLConstants.TYPE_STRING):void

// Get and set the GraphMLIOHandler that will be used for graph serialization.
// A custom set of GraphML output handlers can be used for serialization by 
// either setting a configured GraphMLIOHandler or by adding/removing output 
// handlers to/from the GraphMLIOHandler instance used by the RoundtripHandler.
function get outputIOHandler():GraphMLIOHandler
function set outputIOHandler(outputIOHandler:GraphMLIOHandler):void

// Get or set whether the GraphMLIOHandler instance that is created for 
// serialization uses the yFiles FLEX/yFiles.NET GraphML extension (true) or 
// the yFiles Java compatible GraphML extension (false).
function get styleMode():Boolean
function set styleMode(styleMode:Boolean):void

Subclassing DownloadHandler

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

Using DefaultServerAction and ResultHandler

In order to implement custom HTTP service request handlers for handling XML formatted server responses, class DefaultServerAction can be used in combination with a custom implementation of the ResultHandler interface. Example 4.3, “Custom Server Action” shows how to use a custom result handler with a DefaultServerAction.

Example 4.3. Custom Server Action

// Custom result handler which displays an alert message that was send from the 
// server.
public class AlertResultHandler implements ResultHandler {
  public function handleResult(result:XML):void {
    var title:String = result.title[0].text()[0];
    var message:String = result.message[0].text()[0];
    Alert.show(message, title);
  }
  
  public function handleError(fault:Fault):void {
    Alert.show(fault.faultString, "Error");
  }
}

// Retrieve a HTTP service instance for the "alertService".
var service:HTTPService = HTTPServiceFactory.getService("alertService");

// Create a result handler instance.
var alertResultHandler:ResultHandler = new AlertResultHandler();

// Create a server action that will call the handleResult or handleError 
// callbacks of the result handler.
var serverAction:DefaultServerAction = 
  new DefaultServerAction(service, alertResultHandler);

// Send the server action.
serverAction.sendAction();