org.graphstream.stream.netstream
Class NetStreamConstants

java.lang.Object
  extended by org.graphstream.stream.netstream.NetStreamConstants

public class NetStreamConstants
extends Object

NetStream

The NetStream framework allows to export the idea of "streams of graph events" to other languages than Java, through a network interface. The aim is mainly to allow the use of GraphStream with other projects written in other languages. However, since it is a network interface it also allows the use of several machines. The protocol is optimized to be have as low overhead as possible.

If you are looking for a Java-to-Java network link between GraphStream and some other project, you may prefer GraphStream's RMI facilities.

This document is organized in 3 sections. The first one details the Receiver's mechanisms. The second section describes the Sender. The last section details the NetStream Protocol.

Receiver

This one is responsible for receiving graph events from the network following the "NetStream" protocol. Events are then dispatched to pipes according to a given names. Here we consider that several stream of events (independent one another) can be handled by the receiver. We thus introduce the idea of stream ID where a stream is identified by an ID.

The Receiver is composed of:

The Receiver's general behavior is:

The graph event receiver listens at a given address and port. It runs on its own thread. Several senders can connect to it, the receiver will demultiplex the data flow and dispatch incoming events to specified pipes. No extra thread are created when client connect.

From the graph event stream point of view, the NetStream receiver can be seen as a set of pipes identified by an id. When an event is received is is directed to one specific stream. By default, senders not willing to handle different streams may send to the stream called "default".

The only way to receive events from the network is to ask for a stream by means of a ThreadProxyPipe to the Receiver. The getStream() and getDefaultStream() give access to such pipe. Asking a non-existing stream (with an unknown id) will create it, so those functions always return a pipe. On the opposite, any new stream introduced by a sender will be created by the receiver.

Example

 import java.io.IOException;
 import java.net.UnknownHostException;
 
 import org.graphstream.graph.Graph;
 import org.graphstream.graph.implementations.MultiGraph;
 import org.graphstream.stream.thread.ThreadProxyPipe;
 
 // A simple example of use of the NetStream receiver.
 
 public class ReceiverExample {
 
        public static void main(String[] args) throws UnknownHostException,
                        IOException, InterruptedException {
                // ----- On the receiver side -----
                //
                // - a graph that will display the received events
                Graph g = new MultiGraph("G");
                g.display();
                // - the receiver that waits for events
                NetStreamReceiver net = new NetStreamReceiver(2001);
                // - received events end up in the "default" pipe
                ThreadProxyPipe pipe = net.getDefaultStream();
                // - plug the pipe to the sink of the graph
                pipe.addSink(g);
                // -The receiver pro-actively checks for events on the ThreadProxyPipe
                while (true) {
                        pipe.pump();
                        Thread.sleep(100);
                }
        }
 }
 

Sender

A sender, from the GraphStream API, is first of all a sink where one can plug sources so that it can receive events. Receiving these events the sender will pack them into messages according to the NetStream Protocol and then send those messages to a defined receiver through a given port, host and stream ID.

Example

 import java.io.IOException;
 import java.net.UnknownHostException;
 
 import org.graphstream.graph.Graph;
 import org.graphstream.graph.implementations.MultiGraph;
 
 // A simple example of use of the NetStream sender.
 
 public class SenderExample {
 
        public static void main(String[] args) {
                Graph g = new MultiGraph("G");
                // - the sender
                NetStreamSender nsc = null;
                try {
                        nsc = new NetStreamSender(2001);
                } catch (UnknownHostException e) {
                        e.printStackTrace();
                } catch (IOException e) {
                        e.printStackTrace();
                }
                // - plug the graph to the sender so that graph events can be
                // sent automatically
                g.addSink(nsc);
                // - generate some events on the client side
                String style = "node{fill-mode:plain;fill-color:#567;size:6px;}";
                g.addAttribute("stylesheet", style);
                g.addAttribute("ui.antialias", true);
                g.addAttribute("layout.stabilization-limit", 0);
                for (int i = 0; i < 500; i++) {
                        g.addNode(i + "");
                        if (i > 0) {
                                g.addEdge(i + "-" + (i - 1), i + "", (i - 1) + "");
                                g.addEdge(i + "--" + (i / 2), i + "", (i / 2) + "");
                        }
                }
        }
 
 }
 

The NetStream Protocol

Messages in the NetStream protocol are specified a the byte level. It is different than an XML-based protocols like client/server REST approaches. Here the content and different formats constituting a message are optimize as much as possible, so as to reduce the network payload.

A message, as it is created by a sender, is composed of three main parts:

  1. A 4 bytes integer that indicates the size (in bytes) of the remaining of this message (not including those 4 bytes).
  2. A string, encoded using the NetStream protocol (see TYPE_STRING below), that identifies the stream targeted by this event.
  3. The event itself, that can be decoded, according to the NetStream protocol.

Data Types

Before sending a value whose type is unknown (integer, double, string, array...) one have to specify its type (and if applicable, its length) to the server. Value types are defined to allow the server to recognize the type of a value. When applicable (strings, tables, raw data) types are followed by a length. This length is always coded with a 16-bits signed short and usually represents the number of elements (for arrays).

Graph Events

the graph event, as created by a sender, is the third part of the whole sent message. It is made of several parts that differ according the event. The common information is the first byte of the event, that identifies the event. Then, other data depending on the event follow up. Those event identifiers are one byte long. To avoid problems between languages (mainly because of java) those bytes are unsigned and only positive values are used. So, any event identifier will take a value between 0 and 127.

Here is a list of graph event identifiers followed by the expected information to fulfill these events:

Copyright (c) 2010-2012 University of Luxembourg - University of Le Havre NetStreamConstants.java

Since:
Aug 3, 2011
Author:
Yoann Pigné

Field Summary
static int COMMAND
          Constant that indicates that this message is a COMMAND, not and EVENT.
static int EVENT_ADD_EDGE
          Followed by - an edge id (TYPE_STRING format), - an source node id (TYPE_STRING format), - a target node id (TYPE_STRING format - a boolean indicating if directed (TYPE_BOOLEAN format)
static int EVENT_ADD_EDGE_ATTR
          Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute value
static int EVENT_ADD_GRAPH_ATTR
          Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute value
static int EVENT_ADD_NODE
          Followed by a node id (TYPE_STRING format)
static int EVENT_ADD_NODE_ATTR
          Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute value
static int EVENT_CHG_EDGE_ATTR
          Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute old value - the attribute new value
static int EVENT_CHG_GRAPH_ATTR
          Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute old value - the attribute new value
static int EVENT_CHG_NODE_ATTR
          Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute old value - the attribute new value
static int EVENT_CLEARED
           
static int EVENT_DEL_EDGE
          Followed by an edge id (TYPE_STRING format)
static int EVENT_DEL_EDGE_ATTR
          Followed by - the edge id (TYPE_STRING format) - the attribute id (TYPE_STRING format)
static int EVENT_DEL_GRAPH_ATTR
          Followed by - the attribute id (TYPE_STRING format)
static int EVENT_DEL_NODE
          Followed by a node id (TYPE_STRING format)
static int EVENT_DEL_NODE_ATTR
          Followed by - the node id (TYPE_STRING format) - the attribute id (TYPE_STRING format)
static int EVENT_END
          Constant indicating that the client has disconnected.
static int EVENT_GETVERSION
          Followed by an 32-bit signed integer for this protocol version.
static int EVENT_START
          Not used.
static int EVENT_STEP
          Followed by double (TYPE_DOUBLE format)
static byte TYPE_ARRAY
          An type-unspecified array.
static int TYPE_BOOLEAN
          Followed by a byte who's value is 0 or 1
static int TYPE_BOOLEAN_ARRAY
          An array of booleans.
static int TYPE_BYTE
          Followed by a signed byte [-127,127]
static int TYPE_BYTE_ARRAY
          An array of bytes.
static int TYPE_DOUBLE
          Followed by a double precision 64-bits floating point number
static int TYPE_DOUBLE_ARRAY
          Array of double.
static int TYPE_FLOAT
          Followed by a single precision 32-bits floating point number
static int TYPE_FLOAT_ARRAY
          Array of double.
static int TYPE_INT
          Followed by an 32-bit signed integer
static int TYPE_INT_ARRAY
          An array of integers.
static int TYPE_LONG
          Followed by an 64-bit signed integer
static int TYPE_LONG_ARRAY
          An array of longs.
static int TYPE_RAW
          Raw data, good for serialization.
static int TYPE_SHORT
          Followed by an 16-bit signed integer (a short)
static int TYPE_SHORT_ARRAY
          An array of shorts.
static int TYPE_STRING
          Array of characters.
 
Constructor Summary
NetStreamConstants()
           
 
Method Summary
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EVENT_GETVERSION

public static int EVENT_GETVERSION
Followed by an 32-bit signed integer for this protocol version. Certainly useless.


EVENT_START

public static int EVENT_START
Not used.


EVENT_END

public static int EVENT_END
Constant indicating that the client has disconnected.


EVENT_ADD_NODE

public static int EVENT_ADD_NODE
Followed by a node id (TYPE_STRING format)


EVENT_DEL_NODE

public static int EVENT_DEL_NODE
Followed by a node id (TYPE_STRING format)


EVENT_ADD_EDGE

public static int EVENT_ADD_EDGE
Followed by - an edge id (TYPE_STRING format), - an source node id (TYPE_STRING format), - a target node id (TYPE_STRING format - a boolean indicating if directed (TYPE_BOOLEAN format)


EVENT_DEL_EDGE

public static int EVENT_DEL_EDGE
Followed by an edge id (TYPE_STRING format)


EVENT_STEP

public static int EVENT_STEP
Followed by double (TYPE_DOUBLE format)


EVENT_CLEARED

public static int EVENT_CLEARED

EVENT_ADD_GRAPH_ATTR

public static int EVENT_ADD_GRAPH_ATTR
Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute value


EVENT_CHG_GRAPH_ATTR

public static int EVENT_CHG_GRAPH_ATTR
Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute old value - the attribute new value


EVENT_DEL_GRAPH_ATTR

public static int EVENT_DEL_GRAPH_ATTR
Followed by - the attribute id (TYPE_STRING format)


EVENT_ADD_NODE_ATTR

public static int EVENT_ADD_NODE_ATTR
Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute value


EVENT_CHG_NODE_ATTR

public static int EVENT_CHG_NODE_ATTR
Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute old value - the attribute new value


EVENT_DEL_NODE_ATTR

public static int EVENT_DEL_NODE_ATTR
Followed by - the node id (TYPE_STRING format) - the attribute id (TYPE_STRING format)


EVENT_ADD_EDGE_ATTR

public static int EVENT_ADD_EDGE_ATTR
Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute value


EVENT_CHG_EDGE_ATTR

public static int EVENT_CHG_EDGE_ATTR
Followed by - an attribute id (TYPE_STRING format) - the attribute TYPE - the attribute old value - the attribute new value


EVENT_DEL_EDGE_ATTR

public static int EVENT_DEL_EDGE_ATTR
Followed by - the edge id (TYPE_STRING format) - the attribute id (TYPE_STRING format)


TYPE_BOOLEAN

public static int TYPE_BOOLEAN
Followed by a byte who's value is 0 or 1


TYPE_BOOLEAN_ARRAY

public static int TYPE_BOOLEAN_ARRAY
An array of booleans. Followed by first, a 16-bits integer for the number of booleans and then, a list of bytes who's value is 0 or 1


TYPE_BYTE

public static int TYPE_BYTE
Followed by a signed byte [-127,127]


TYPE_BYTE_ARRAY

public static int TYPE_BYTE_ARRAY
An array of bytes. Followed by first, a 16-bits integer for the number of integers and then, a list of signed bytes.


TYPE_SHORT

public static int TYPE_SHORT
Followed by an 16-bit signed integer (a short)


TYPE_SHORT_ARRAY

public static int TYPE_SHORT_ARRAY
An array of shorts. Followed by first, a 16-bits integer for the number of integers and then, a list of 16-bit signed shorts


TYPE_INT

public static int TYPE_INT
Followed by an 32-bit signed integer


TYPE_INT_ARRAY

public static int TYPE_INT_ARRAY
An array of integers. Followed by first, a 16-bits integer for the number of integers and then, a list of 32-bit signed integers


TYPE_LONG

public static int TYPE_LONG
Followed by an 64-bit signed integer


TYPE_LONG_ARRAY

public static int TYPE_LONG_ARRAY
An array of longs. Followed by first, a 16-bits integer for the number of longs and then, a list of 62-bit signed integers


TYPE_FLOAT

public static int TYPE_FLOAT
Followed by a single precision 32-bits floating point number


TYPE_FLOAT_ARRAY

public static int TYPE_FLOAT_ARRAY
Array of double. Followed by first, a 16-bits integer for the number of floats and then, a list of 32-bit floats


TYPE_DOUBLE

public static int TYPE_DOUBLE
Followed by a double precision 64-bits floating point number


TYPE_DOUBLE_ARRAY

public static int TYPE_DOUBLE_ARRAY
Array of double. Followed by first, a 16-bits integer for the number of doubles and then, a list of 64-bit doubles


TYPE_STRING

public static int TYPE_STRING
Array of characters. Followed by first, a 16-bits integer for the size in bytes (not in number of characters) of the string, then by the unicode string


TYPE_RAW

public static int TYPE_RAW
Raw data, good for serialization. Followed by first, a 16-bits integer indicating the length in bytes of the dataset, and then the data itself.


TYPE_ARRAY

public static byte TYPE_ARRAY
An type-unspecified array. Followed by first, a 16-bits integer indicating the number of elements, and then, the elements themselves. The elements themselves have to give their type.


COMMAND

public static int COMMAND
Constant that indicates that this message is a COMMAND, not and EVENT. For now it is followed by a string that has to be parssed at the application level. THIS IS EXPERIMENTAL AND MAY (WILL) CHANGE !

Constructor Detail

NetStreamConstants

public NetStreamConstants()


Copyright © 2012. All Rights Reserved.