Wiki source code of The API of KWebS
Last modified by Alexander Schulz-Rosengarten on 2023/07/11 10:33
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
1.1 | 1 | KWebS provides a simple to use API, it consists of only three operations. While the main operation {{code language="none"}}graphLayout{{/code}} provides the core functionality, you can use the operations {{code language="none"}}getServiceData{{/code}} and {{code language="none"}}getPreviewImage{{/code}} to retrieve the meta data that describes the layout a server provides. In the following you will see how you can use these operations to integrate automatic layout into your application. Although the public interface is declared by the contract of the SOAP web service KWebS uses, we will use the java notation because it fosters understandability. |
| 2 | |||
| 3 | = The Operation {{code language="none"}}graphLayout{{/code}} = | ||
| 4 | |||
| 5 | The central operation of KWebS is {{code language="none"}}graphLayout{{/code}}, which is shown in the listing below. It calculates the layout of a graph that you deliver in serial notation as the {{code language="none"}}serializedGraph{{/code}} parameter. This parameter is declaring a general serial notation. The server has to know the underlying meta model and form of serialization, therefore, you have to define the //format// you used to submit your graph with the {{code language="none"}}informat{{/code}} parameter. In general, when the server has calculated the layout, it delivers the graph for which the layout was calculated in the same format that you chose to submit your source graph. Alternatively, you can define a different output format with the parameter {{code language="none"}}outformat{{/code}} and the server performs the necessary translation. | ||
| 6 | |||
| |
18.1 | 7 | There is a [[wiki page>>doc:KIELER.Discontinued Projects.Web Services (KWebS).Graph Formats.WebHome]] explaining the currently supported graph formats. |
| |
1.1 | 8 | |
| 9 | {{code theme="Eclipse" language="java"}} | ||
| 10 | /** | ||
| 11 | * Calculating the layout of a graph with KWebS | ||
| 12 | * | ||
| 13 | * @param serializedGraph the serial notation of the source graph | ||
| 14 | * @param informat the format of the source graph | ||
| 15 | * @param outformat the optional format of the result | ||
| 16 | * @param options the optional layout options | ||
| 17 | * | ||
| 18 | * @return the serial notation of the graph with calculated layout either | ||
| 19 | * in the format of the source graph or a format chosen by the user | ||
| 20 | */ | ||
| 21 | String graphLayout( | ||
| 22 | String serializedGraph, | ||
| 23 | String informat, | ||
| 24 | String outformat, | ||
| 25 | List<GraphLayoutOption> options | ||
| 26 | ); | ||
| 27 | {{/code}} | ||
| 28 | |||
| |
3.1 | 29 | The optional parameter {{code language="none"}}options{{/code}} gives you the possibility to declare a set of layout options. While the algorithm to be used for calculating the layout of the graph is the most important one, you can choose among a variety of other options, e.g. the orientation of edges or the spacing between nodes. Each option is identified by a string based identifier and a corresponding string based value. The following listing shows the according {{code language="none"}}GraphLayoutOption{{/code}} data type of the API provided by KWebS. |
| |
1.1 | 30 | |
| 31 | {{code theme="Eclipse" language="java"}} | ||
| 32 | public class GraphLayoutOption { | ||
| 33 | public String id; | ||
| 34 | public String value; | ||
| 35 | } | ||
| 36 | {{/code}} | ||
| 37 | |||
| |
3.1 | 38 | The layout options a server supports are part of the services meta data that are discussed below. Each layout option is connected to a specific type of graph element. While one option only refers to nodes, another option is only applicable to edges. When you define layout options via the {{code language="none"}}options{{/code}} parameter, the server applies each declared option to every compatible graph element. If you want to specify layout options to a specific graph element, you have to do this in the source graph. The server will not overwrite options declared in the source graph if the same option is part of the options list. |
| |
1.1 | 39 | |
| |
3.1 | 40 | = The operation {{code language="none"}}getServiceData{{/code}} = |
| |
1.1 | 41 | |
| 42 | KWebS leverages the layout of the KIELER project, which is being developed actively, therefore the provided layout may change over time due to additions, removements, or updates on layout algorithms, options, and supported formats. Furthermore, due to its open source and Eclipse nature, providers may decide to add own implementations of the before mentioned components or to support only a subset of these. Therefore, each service instance provides meta data about the layout it supports. You can retrieve the meta data by invoking the operation {{code language="none"}}getServiceData{{/code}}, which is shown in the following listing. | ||
| 43 | |||
| 44 | {{code theme="Eclipse" language="java"}} | ||
| 45 | String getServiceData(); | ||
| 46 | {{/code}} | ||
| 47 | |||
| |
17.1 | 48 | When you use this operation, you receive a XML notation of the meta data. It is based on an //Ecore// meta model named //ServiceData//, which is shown by the next figure, and reuses the structure of the extension point {{code language="none"}}layoutProviders{{/code}} of [[KIML>>doc:KIELER.Discontinued Projects.Infrastructure for Meta Layout (KIML).WebHome]]. |
| |
1.1 | 49 | |
| 50 | [[image:attach:ServiceData.png]] | ||
| 51 | |||
| 52 | At startup time, the server initializes a model instance of ServiceData from the extensions the layout related plugins from KIELER make to {{code language="none"}}layoutProviders{{/code}}. Additionaly, it adds service related information, e.g. the supported formats, to the model instance. When you request the meta data of a service, you receive the serial notation of the ServiceData model instance in XMI. By providing a structured model for its meta data, KWebS eases the integration of the service-based layout in software systems on the programmatic level. | ||
| 53 | |||
| 54 | The structure of the ServiceData meta model is quite simple. The core element is {{code language="none"}}ServiceData{{/code}}. Its attribute {{code language="none"}}version{{/code}} declares the runtime version of the server. It contains the following children: | ||
| 55 | |||
| 56 | * {{code language="none"}}LayoutAlgorithm{{/code}} declares a layout algorithm supported by the server. Besides the attributes {{code language="none"}}name{{/code}} and {{code language="none"}}description{{/code}}, which provide the name and a textual description of the layout the algorithm calculates, the attribute **id** declares the identifier that can be used in combination with the layout option identified by {{code language="none"}}de.cau.cs.kieler.algorithm{{/code}} to specify which algorithm the server shall use when you invoke the layout by using its {{code language="none"}}graphLayout{{/code}} operation. | ||
| 57 | |||
| 58 | * {{code language="none"}}LayoutType{{/code}} declares the general type of layout an algorithm computes, e.g. //circular// or //orthogonal// layout. Again, the attributes {{code language="none"}}name{{/code}} and {{code language="none"}}description{{/code}} provide the name and additional textual information. | ||
| 59 | |||
| 60 | * ((( | ||
| |
16.1 | 61 | {{code language="none"}}LayoutOption{{/code}} declares a layout option. The attribute {{code language="none"}}type{{/code}} defines the type of values you may assign to this option, e.g. boolean, string or enumeration values. Additionaly, the attribute {{code language="none"}}default{{/code}} may carry a default value which generally provides good layout results. As said before, a layout option is related to specific types of graph elements, specified by the attribute {{code language="none"}}appliesTo{{/code}}. It may be empty, meaning, an option can be applied to any element, or contain a comma separated list of compatible element types. The attribute {{code language="none"}}id{{/code}} declares the identifier of the layout option. You can use it to specify a layout option directly in the source graph by annotating a specific graph element. The way you realize the annotation is dependent on the model you use. For example, if you use a [[KGraph>>doc:KIELER.Discontinued Projects.Infrastructure for Meta Layout (KIML).KGraph Meta Model.WebHome]] model, you could do it like the following listing shows: |
| |
1.1 | 62 | |
| 63 | {{code theme="Eclipse" language="java"}} | ||
| 64 | // Retrieve the graph model somehow | ||
| 65 | KNode graph = ... | ||
| 66 | |||
| 67 | // Get the layout related information from the root node | ||
| 68 | KShapeLayout shapeLayout = graph.getData(KShapeLayout.class); | ||
| 69 | |||
| 70 | // Create a property which is used to define the layout algorithm and | ||
| 71 | // use KLay layered as the default algorithm | ||
| 72 | IProperty<String> algorithm = new Property<String>( | ||
| 73 | "de.cau.cs.kieler.algorithm", | ||
| 74 | "de.cau.cs.kieler.klay.layered" | ||
| 75 | ); | ||
| 76 | |||
| 77 | // Annotate the root node of the graph model with the layout option | ||
| 78 | // represented by the property and use the default algorithm KLay | ||
| 79 | // layered | ||
| 80 | shapeLayout.setProperty(algorithm, algorithm.getDefault()); | ||
| 81 | |||
| 82 | // Alternatively, you can use a different algorithm like the graphviz DOT | ||
| 83 | shapeLayout.setProperty(algorithm, "de.cau.cs.kieler.graphviz.dot"); | ||
| 84 | {{/code}} | ||
| 85 | |||
| |
11.3 | 86 | You could alternatively use the {{code language="none"}}options{{/code}} parameter of the {{code language="none"}}graphLayout{{/code}} operation to declare a specific layout algorithm, as you can see in the next listing. The {{code language="none"}}layoutServicePort{{/code}} instance the example uses resembles the //proxy// necessary to interact with the layout server. You will see how you can create such a proxy in [[How to use the service based layout in your project>>doc:KIELER.How to Use the Service-Based Layout in Your Project]]. |
| |
1.1 | 87 | |
| 88 | {{code theme="Eclipse" language="java"}} | ||
| 89 | // Retrieve the graph model somehow | ||
| 90 | KNode graph = ... | ||
| 91 | |||
| 92 | // Get the models XMI notation | ||
| 93 | String source = modelToXmi(graph); | ||
| 94 | |||
| 95 | // Create the options list | ||
| 96 | List<GraphLayoutOption> options = new ArrayList<GraphLayoutOption>(); | ||
| 97 | |||
| 98 | // Declare the option defining the algorithm to be used | ||
| 99 | GraphLayoutOption option = new GraphLayoutOption(); | ||
| 100 | |||
| 101 | option.setId("de.cau.cs.kieler.algorithm"); | ||
| 102 | option.setValue("de.cau.cs.kieler.klay.layered"); | ||
| 103 | |||
| 104 | // Add the option declaring the layout algorithm to the list | ||
| 105 | options.add(option); | ||
| 106 | |||
| 107 | // Invoke the service | ||
| 108 | String result = layoutServicePort.graphLayout( | ||
| 109 | source, // the source model | ||
| 110 | "de.cau.cs.kieler.kgraph", // we use the KGraph format | ||
| 111 | null, // we want the service to return the result in KGraph format | ||
| 112 | options // we use the options list to specify the algorithm to be used | ||
| 113 | ); | ||
| 114 | |||
| 115 | // Get the layouted model | ||
| 116 | KNode layout = xmiToModel(result); | ||
| 117 | {{/code}} | ||
| 118 | |||
| 119 | When an option represents an enumeration, it associates a {{code language="none"}}RemoteEnum{{/code}} element. It defines the possible assignments you can make to the option. | ||
| 120 | ))) | ||
| 121 | |||
| 122 | * {{code language="none"}}Category{{/code}} declares a family of algorithms, e.g. KIELER or graphviz. | ||
| 123 | |||
| 124 | * {{code language="none"}}SupportedFormat{{/code}} declares a format that the service supports, e.g. KGraph, GraphML or DOT. The attribute {{code language="none"}}id{{/code}} declares the identifier of the format, which you can use for the {{code language="none"}}informat{{/code}} and the {{code language="none"}}outformat{{/code}} parameter of the {{code language="none"}}graphLayout{{/code}} operation to specify the format of the input graph and the format in which the service shall deliver the layouted graph. | ||
| 125 | |||
| 126 | In general, a layout algorithm supports only a subset of the available layout options. The ServiceData meta model considers this fact by associating a {{code language="none"}}LayoutAlgorithm{{/code}} to its supported {{code language="none"}}LayoutOptions{{/code}} with the {{code language="none"}}KnownOption{{/code}} element, which may hold an alternative default value better suited for the needs of the algorithm. Similarly, the association to a {{code language="none"}}LayoutType{{/code}} and {{code language="none"}}Category{{/code}} element specifies the type of layout and the family it belongs to. | ||
| 127 | |||
| |
3.1 | 128 | = The operation {{code language="none"}}getPreviewImage{{/code}} = |
| |
1.1 | 129 | |
| 130 | A user of graphical modeling is not necessarily familiar with the concepts behind the layout of graphs. To help him choosing an algorithm suited to his needs, a service provides additional information that gives a quick overview of the way an algorithm works. Besides a textual description, which is included in the services meta data, he provides //preview images//, which give a visual impression. Due to the binary nature of these images and their size, they are not part of the meta data and have to be downloaded separately. For this purpose, the {{code language="none"}}LayoutAlgorithm{{/code}} element of the meta data contains the attribute {{code language="none"}}previewImage{{/code}}. It declares an identifier that you can use in combination with the operation {{code language="none"}}getPreviewImage{{/code}}, which the following listing shows, to acquire the binary content of the image~: | ||
| 131 | |||
| 132 | {{code theme="Eclipse" language="java"}} | ||
| 133 | byte[] getPreviewImage(String previewImage); | ||
| 134 | {{/code}} | ||
| 135 | |||
| 136 | Most platforms provide support for creating and displaying images out of their binary representation. Therefore, the {{code language="none"}}getPreviewImage{{/code}} operation gives an easy way to integrate a visual representation of the layout an algorithm calculates in the GUI of a software system. This leverages the comprehension of its users and helps increasing their efficiency. |