public class NetStreamConstants
extends java.lang.Object
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.
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.
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); } } }
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.
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.setAttribute("stylesheet", style); g.setAttribute("ui.antialias", true); g.setAttribute("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) + ""); } } } }
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:
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).
TYPE_BOOLEAN [0x50]
Announces a boolean value. Followed by a byte whose value is 0 (false) or 1 (true).
TYPE_BOOLEAN_ARRAY [0X51]
Announces an array of boolean values. Followed by first, a 32-bit integer that indicates the length of this array, and then, by the actual sequence of booleans.
TYPE_BYTE [0x52]
Announces a byte. Followed by a 8-bit signed byte.
TYPE_INT_BYTE [0x53]
Announces an array of bytes. Followed by first, a 32-bit integer that indicates the length in number of elements of this array, and then, by the actual sequence of 8-bit signed bytes.
TYPE_SHORT [0x54]
Announces a short. Followed by a 16-bit signed short.
TYPE_SHORT_ARRAY [0x55]
Announces an array of shorts. Followed by first, a 32-bit integer that indicates the length in number of elements of this array, and then, by the actual sequence of 16-bit signed shorts.
TYPE_INT [0x56]
Announces an integer. Followed by a 32-bit signed integer.
TYPE_INT_ARRAY [0x57]
Announces an array of integers. Followed by first, a 32-bit integer that indicates the length in number of elements of this array, and then, the actual sequence of 32-bit signed integers.
TYPE_LONG [0x58]
Announces a long. Followed by a 64-bit signed long.
TYPE_LONG_ARRAY [0x59]
Announces an array of longs. Followed by first, a 32-bit integer that indicates the length in number of elements of this array, and then, by the actual sequence of 64-bit signed longs.
TYPE_FLOAT [0x5A]
Announces a float. Followed by a 32-bit single precision signed floating point number.
TYPE_FLOAT_ARRAY [0x5B]
Announces an array of floats. Followed by first, a 32-bit integer that indicates the length in number of elements of this array, and then, by the actual sequence of 32-bit double precision signed floating point numbers.
TYPE_DOUBLE [0x5C]
Announces a double. Followed by a 64-bit double precision signed floating point number.
TYPE_DOUBLE_ARRAY [0x5D]
Announces an array of doubles. Followed by first, a 32-bit integer that indicates the length in number of elements of this array, and then, by the actual sequence of 64-bit double precision signed floating point numbers.
TYPE_STRING [0x5E]
Announces an array of characters. Followed by first, a 32-bits integer for the size in bytes (not in number of characters) of the string, then by the unicode string itself.
TYPE_RAW [0x5F]
Announces raw data, good for serialization or to exchange data the will then be understood in any language (an image, for instance). Followed by first, a 16-bits integer indicating the length in bytes of the dataset, and then by the data itself, as unsigned bytes.
TYPE_ARRAY [0x60]
Announces an undefined-type array. Followed by first, a 32-bits integer indicating the number of elements, and then, the elements themselves. The elements themselves have to give their types. It may contain data of different types or even other arrays.
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:
EVENT_ADD_NODE [0x10]
Add a node. Followed by a node id ( TYPE_STRING format).
EVENT_DEL_NODE [0x11]
Remove a node. Followed by a node id ( TYPE_STRING format)
EVENT_ADD_EDGE [0x12]
Add an edge. Followed by:
EVENT_DEL_NODE [0x13]
Remove an edge. Followed by the string id of this edge.
EVENT_STEP [0x14]
Time step. Followed by a 64-bit double indicating the timestamp.
EVENT_CLEARED [0x15]
Clear the graph. This event will remove any attribute or element in the graph.
EVENT_ADD_GRAPH_ATTR [0x16]
Add an attribute to the graph. Followed by:
EVENT_CHG_GRAPH_ATTR [0x17]
Change an existing attribute on the graph. Followed by:
EVENT_DEL_GRAPH_ATTR [0x18]
Remove an attribute from the graph. Followed by the attribute name (encoded with the TYPE_STRING format).
EVENT_ADD_NODE_ATTR [0x19]
Add an attribute to a node. Followed by:
EVENT_CHG_NODE_ATTR [0x1A]
Change an existing attribute on a given node. Followed by:
EVENT_DEL_NODE_ATTR [0x1B]
Remove an attribute from a given node. Followed by:
EVENT_ADD_EDGE_ATTR [0x1C]
Add an attribute to an edge. Followed by:
EVENT_CHG_EDGE_ATTR [0x1D]
Change an existing attribute on a given edge. Followed by:
EVENT_DEL_EDGE_ATTR [0x1E]
Remove an attribute from a given edge. Followed by:
Modifier and Type | Field and Description |
---|---|
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_NULL |
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.
|
static int |
TYPE_STRING_ARRAY
Array of Array of characters.
|
static int |
TYPE_UNKNOWN |
Constructor and Description |
---|
NetStreamConstants() |
public static int EVENT_GETVERSION
public static int EVENT_START
public static int EVENT_END
public static int EVENT_ADD_NODE
public static int EVENT_DEL_NODE
public static int EVENT_ADD_EDGE
public static int EVENT_DEL_EDGE
public static int EVENT_STEP
public static int EVENT_CLEARED
public static int EVENT_ADD_GRAPH_ATTR
public static int EVENT_CHG_GRAPH_ATTR
public static int EVENT_DEL_GRAPH_ATTR
public static int EVENT_ADD_NODE_ATTR
public static int EVENT_CHG_NODE_ATTR
public static int EVENT_DEL_NODE_ATTR
public static int EVENT_ADD_EDGE_ATTR
public static int EVENT_CHG_EDGE_ATTR
public static int EVENT_DEL_EDGE_ATTR
public static int TYPE_UNKNOWN
public static int TYPE_BOOLEAN
public static int TYPE_BOOLEAN_ARRAY
public static int TYPE_BYTE
public static int TYPE_BYTE_ARRAY
public static int TYPE_SHORT
public static int TYPE_SHORT_ARRAY
public static int TYPE_INT
public static int TYPE_INT_ARRAY
public static int TYPE_LONG
public static int TYPE_LONG_ARRAY
public static int TYPE_FLOAT
public static int TYPE_FLOAT_ARRAY
public static int TYPE_DOUBLE
public static int TYPE_DOUBLE_ARRAY
public static int TYPE_STRING
public static int TYPE_STRING_ARRAY
public static int TYPE_RAW
public static byte TYPE_ARRAY
public static int TYPE_NULL
public static int COMMAND