UbiGraph XML-RPC Manual

Ubigraph is a system for visualizing dynamic graphs. This version is shipped in binary form as a standalone server that responds to requests using XML-RPC. This makes it easy to use from C, C++, Java, Ruby, Python, and other languages for which XML-RPC implementations are available. Since XML-RPC uses TCP-IP, the server (which visualizes the graph) can be run on a different machine/operating system than the client (which is manipulating the graph). It is also possible to have multiple clients updating the graph simultaneously. (Note that for clients to be on different machines from the server, firewalls must be configured to allow traffic on port 20738.)

Getting started

This version of the ubigraph software is shipped in binary form as a standalone server. Clients talk to the server using XML-RPC, a standard remote procedure call protocol that uses HTTP-POST requests to call methods. The method call and return results are encoded with XML. The use of XML-RPC makes it trivial to use Ubigraph with popular scripting languages such as Python and Ruby.

Starting and using the server

The server process must be started before any clients can connect to it. To do this, just run the ubigraph_server program found in the bin subdirectory of the distribution. You should be rewarded with a message ("Running Ubigraph/XML-RPC server.") and a new window which is empty and black. If you get an error message such as "Failed to bind listening socket to port number 20738," check if the server is already running.

You can now run the programs included in the examples subdirectory of the distribution. The GUI is quite primitive but supports panning (by dragging the mouse). Some of the keys recognized include:

Debugging the XML protocol layer

You shouldn't need to worry about the XML layer unless you are implementing your own client interface in some language that is not yet supported. However, if you're curious to see what the messages being sent to and from the server look like, set XMLRPC_TRACE_XML=1 in your environment before running ubigraph_server. Here is an example call-response pair, which creates a new edge from vertex 0 to vertex 9, which is given an edge-id 423265977 by the server.

XML-RPC CALL:

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
<methodName>ubigraph.new_edge</methodName>
<params>
<param><value><i4>9</i4></value></param>
<param><value><i4>0</i4></value></param>
</params>
</methodCall>

XML-RPC RESPONSE:

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
<params>
<param><value><i4>423265977</i4></value></param>
</params>
</methodResponse>

The basic API functions

The five functions shown below cover the basic operations. API functions are presented in C language syntax, but the way these are adapted to other languages is straightforward.

void        ubigraph_clear();
int         ubigraph_new_vertex();
int         ubigraph_new_edge(int x, int y);
int         ubigraph_remove_vertex(int x);
int         ubigraph_remove_edge(int e);

ubigraph_clear resets the graph, deleting any vertices and edges that exist. It's a good idea to call this method at the beginning of any session, in case a previous client failed to clean up.

new_vertex creates a vertex, and returns its vertex-id (an integer). You need to remember this vertex-id to create edges with new_edge, which creates an edge between two vertices (specified by their vertex-ids), and returns its edge-id (an integer). To delete a vertex, call ubigraph_remove_vertex and supply its vertex-id; any edges touching the vertex are removed also. To delete an edge, call ubigraph_remove_edge and supply its edge-id. The remove methods return 0 on success, or -1 on failure (i.e., you tried to remove an edge or vertex that did not exist.)

Specifying vertex and edge ids

If you do not want to keep track of vertex or edge-id's, there is an alternate pair of API routines that allow you to specify the vertex-id and edge-id when creating vertices and edges:

int         ubigraph_new_vertex_w_id(int id);
int         ubigraph_new_edge_w_id(int id, int x, int y);

Language Bindings

In the xmlrpc subdirectory of the distribution you can find bindings and/or examples of how to use the ubigraph server from various programming languages.

Python and Ruby are the easiest to get working, since XML-RPC is included in the standard libraries for these languages. For Java, you will need to install a .jar package for XMLRPC support. For C and C++ you will need to build and install the XMLRPC-C librares.

Python

XML-RPC is included in the python standard library. An example usage is shown below:

import xmlrpclib

# Create an object to represent our server.
server_url = 'http://127.0.0.1:20738/RPC2'
server = xmlrpclib.Server(server_url)
G = server.ubigraph

# Create a graph
for i in range(0,10):
    G.new_vertex_w_id(i)

# Make some edges
for i in range(0,10):
    G.new_edge(i, (i+1)%10)

Using Python interactively

Python provides an easy way to experiment with the API and styles. If you start an interactive Python session and paste in the first few lines above, you can then generate some vertices and play with their styles.

$ python
Python 2.3.5 (#1, Apr 25 2007, 00:02:14) 
Type "help", "copyright", "credits" or "license" for more information.
>>> import xmlrpclib
>>> server = xmlrpclib.Server('http://localhost:20738/RPC2')
>>> G = server.ubigraph
>>> x = G.new_vertex()
>>> y = G.new_vertex()
>>> G.new_edge(x,y)
335979033
>>> G.set_vertex_attribute(x, 'color', '#ff0000')
0
>>> G.set_vertex_attribute(y, 'shape', 'torus')
0
>>> G.set_vertex_attribute(y, 'color', '#ffff40')
0
>>> G.set_vertex_attribute(x, 'label', 'This is red')
0

Ruby

XML-RPC is included with Ruby. Here is an example program:

require 'xmlrpc/client'

server = XMLRPC::Client.new2("http://127.0.0.1:20738/RPC2")

for id in (0..9)
  server.call("ubigraph.new_vertex_w_id", id)
end

for id in (0..9)
  server.call("ubigraph.new_edge", id, (id+1)%10)
end

Java

You will need to install Apache XML-RPC for Java, which can be obtained from http://ws.apache.org/xmlrpc/. The .jar files in the lib subdirectory of the Apache XML-RPC binary distribution should be placed in your usual CLASSPATH. (In Mac OS X, they can be copied to /System/Library/Java/Extensions.)

In the xmlrpc/Java subdirectory of the ubigraph distribution you will find ubigraph.jar, which provides a class org.ubiety.ubigraph.UbigraphClient that hides the xmlrpc details. Javadoc for this class can be found in the xmlrpc/Java/html subdirectory of the distribution. An example use is shown below:

import org.ubiety.ubigraph.UbigraphClient;

public class Example {

public static void main(String[] args) {
  UbigraphClient graph = new UbigraphClient();

  int N = 10;
  int[] vertices = new int[N];

  for (int i=0; i < N; ++i)
    vertices[i] = graph.newVertex();

  for (int i=0; i < N; ++i)
    graph.newEdge(vertices[i], vertices[(i+1)%N]);
}

}

C

An API is provided for C and C++ that hides the underlying XML-RPC implementation. Once you have this API built, using it is very simple, e.g.:

#include <UbigraphAPI.h>

int main(int const argc, const char ** const argv)
{
  int i;
  for (i=0; i < 10; ++i)
    ubigraph_new_vertex_w_id(i);

  for (i=0; i < 10; ++i)
    ubigraph_new_edge(i, (i+1)%10);

  sleep(2);

  ubigraph_clear();
}

Building the C language API

The xmlrpc/C subdirectory of the ubigraph distribution contains some things you will need to build. Here is how to proceed:

1. If you do not already have it, you will need to download, build, and install XML-RPC for C/C++ (Xmlrpc-c), which can be obtained from http://xmlrpc-c.sourceforge.net/. (This may require installing a development version of libwww.)
2. In the xmlrpc/C subdirectory of the ubigraph distribution, you will need to do "make libubigraphclient" to build a library (libubigraphclient.a) which provides the C language API.
3. At this point you should be able to build and run the example program in the xmlrpc/C subdirectory. (Start the server first, of course.)
4. To use the C API in your own programs, you will #include <UbigraphAPI.h>. This requires that you put the ubigraph include directory (where UbigraphAPI.h is found) in your include path (using -I). When linking, these libraries will be required:

   -lubigraphclient -lxmlrpc_client -lxmlrpc -lxmlrpc_util 
   -lxmlrpc_xmlparse -lxmlrpc_xmltok
   

   The xmlrpc libraries should be installed in one of the standard library paths (e.g., /usr/include/lib). For the linker to find libubigraphclient.a, you will need to either copy this to a standard library path, or include the path with a -L option.

C++

Follow the instructions for C, above. Use extern "C" when including the header file, e.g.:

extern "C" {
#include <UbigraphAPI.h>
}

int main(int const argc, const char ** const argv)
{
  for (int i=0; i < 10; ++i)
    ubigraph_new_vertex_w_id(i);

  for (int i=0; i < 10; ++i)
    ubigraph_new_edge(i, (i+1)%10);

  sleep(2);

  ubigraph_clear();
}

Styles

Vertex styles

Vertex style attributes can be set with the following function:

int   ubigraph_set_vertex_attribute(vertex_id_t x,
        string attribute, string value);

However, if you have a large number of vertices with similar attributes, you should use style-ids, as described below.

The table below shows currently supported style attributes.

Attribute	Values	Default
color	String of the form "#000000" specifying an rgb triple.	"#0000ff"
shape		"sphere"
shapedetail	Indicates the level of detail with which the shape should be rendered. This is relevant only for the sphere, cone, and torus shapes, which are described by polygons. Performance may improve for large graphs if the level of detail is reduced.	10
label	A string to be displayed near the vertex.	""
labelpos	Where to display the label, relative to the vertex. This vector is multiplied by the vertex size to calculate the label offset. (i.e., if you double the size of a vertex, the label position will automatically adjust itself.) Implemented in libubiety, but yet in UbigraphAPI.	[0,1.2,0]
orientation	3-vector indicating the direction in which the shape is oriented. Not yet implemented.	"[0.0,1.0,0.0]".
size	Real number indicating the relative size of the shape.	1.0
fontcolor	String of the form "#000000" specifying an rgb triple.	"#ffffff"
fontfamily	String indicating the font to be used for the label. Recognized choices are "Helvetica" and "Times Roman". Only the combinations of family and size shown below are recognized; other choices of family and size result in a best guess.	Helvetica
fontsize	Integer giving the size of the font, in points, used for the label.	12
manifold	The id of a manifold to which this vertex should be restricted. Not yet implemented.	0

Edge styles

Style-ids and the style model

result_t    ubigraph_new_style(style_id_t parent_style);
result_t    ubigraph_set_style_attribute(style_id_t s,
              const char* attribute, const char* value);
result_t    ubigraph_set_vertex_style(vertex_id_t x, style_id_t s);

Manifolds