Summary

• Page properties (1 modified, 0 added, 0 removed)
• Objects (1 modified, 0 added, 0 removed)
  • Confluence.Code.ConfluencePageClass[0]

Details

Page properties

Content

...	...	@@ -1,15 +2,11 @@
1		-(% style="" %)
2	2	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.
3	3
4	4	= The Operation {{code language="none"}}graphLayout{{/code}} =
5	5
6		-(% style="" %)
7	7	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.
8	8
9		-(% style="" %)
10	10	At the moment, KWebS supports six different formats:
11	11
12		-(% style="" %)
13	13	* the KIELER [[KGraph>>doc:KGraph Meta Model]] in its XML Metadata Interchange (XMI) notation, the identifier is {{code language="none"}}de.cau.cs.kieler.kgraph{{/code}},
14	14	* Graphviz DOT ([[http:~~/~~/www.graphviz.org/content/dot-language>>url:http://www.graphviz.org/content/dot-language||shape="rect"]]), the identifier is {{code language="none"}}org.graphviz.dot{{/code}},
15	15	* GraphML ([[http:~~/~~/graphml.graphdrawing.org/specification.html>>url:http://graphml.graphdrawing.org/specification.html||shape="rect"]]), the identifier is {{code language="none"}}org.graphdrawing.graphml{{/code}},
...	...	@@ -37,7 +37,7 @@
37	37	);
38	38	{{/code}}
39	39
40		-(% style="" %)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.
	36	+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.
41	41
42	42	{{code theme="Eclipse" language="java"}}
43	43	public class GraphLayoutOption {
...	...	@@ -46,11 +46,10 @@
46	46	}
47	47	{{/code}}
48	48
49		-(% style="" %)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.
	45	+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.
50	50
51		-= The operation getServiceData =
	47	+= The operation {{code language="none"}}getServiceData{{/code}} =
52	52
53		-(% style="" %)
54	54	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.
55	55
56	56	{{code theme="Eclipse" language="java"}}
...	...	@@ -57,25 +57,18 @@
57	57	String getServiceData();
58	58	{{/code}}
59	59
60		-(% style="" %)
61	61	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:Infrastructure for Meta Layout (KIML)]].
62	62
63		-(% style="" %)
64	64	[[image:attach:ServiceData.png]]
65	65
66		-(% style="" %)
67	67	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.
68	68
69		-(% style="" %)
70	70	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:
71	71
72		-(% style="" %)
73	73	* {{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.
74	74
75		-(% style="" %)
76	76	* {{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.
77	77
78		-(% style="" %)
79	79	* (((
80	80	{{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:KGraph Meta Model]] model, you could do it like the following listing shows:
81	81
...	...	@@ -138,18 +138,14 @@
138	138	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.
139	139	)))
140	140
141		-(% style="" %)
142	142	* {{code language="none"}}Category{{/code}} declares a family of algorithms, e.g. KIELER or graphviz.
143	143
144		-(% style="" %)
145	145	* {{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.
146	146
147		-(% style="" %)
148	148	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.
149	149
150		-= The operation getPreviewImage =
	135	+= The operation {{code language="none"}}getPreviewImage{{/code}} =
151	151
152		-(% style="" %)
153	153	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~:
154	154
155	155	{{code theme="Eclipse" language="java"}}
...	...	@@ -156,5 +156,4 @@
156	156	byte[] getPreviewImage(String previewImage);
157	157	{{/code}}
158	158
159		-(% style="" %)
160	160	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.

Confluence.Code.ConfluencePageClass[0]

Id

...	...	@@ -1,1 +1,1 @@
1		-885178
	1	+885185

URL

...	...	@@ -1,1 +1,1 @@
1		-https://rtsys.informatik.uni-kiel.de/confluence//wiki/spaces/KIELER/pages/885178/The API of KWebS
	1	+https://rtsys.informatik.uni-kiel.de/confluence//wiki/spaces/KIELER/pages/885185/The API of KWebS