Exploring The Graph API

Graph

The Graph class represents a property graph. It currently has 2 core implementations: UndirectedGraph and DirectedGraph. There are also implementations which support greenrobot’s EventBus. A graph can be created using constructors.

var undirected= new UndirectedGraph<String>();
var directed = new DirectedGraph<String>();

creating elements

Vertex and edge elements are added to the graph through vertex and edge methods. Elements may also be found using the find methods. There are two important types of element creation methods. First there are the methods which return the Graph. These methods allow the developer to build a graph using method chaining. Then there are methods which return the element. These methods allow the developer to build an element using method chaining.

method chain on graph object

graph.vertex("A").edge("B", "C");

This line creates vertex "A" and then creates edge "B"→"C".

method chain on vertex object

graph.getVertex("A", "shape", "square").property("color", "blue").connectsTo("B");

This line creates vertex "A" with a property shape set to square. It then adds the property blue to the vertex and adds and edge connecting to "B".

finding elements

Find methods return an Optional that may contain the graph element. find methods exist for vertices and edges. The returned optional can be used to perform optional operations on the element.

findEdge("A", "B").ifPresentOrElse(v -> v.property("count", ((Integer) v.getProperty("count")) + 1), () -> graph.getEdge("A", "B").property("count", Integer.valueOf(0));

removing elements

Elements can be removed using the remove methods.

graph.removeVertex("A");
graph.removeEdge("B", "C");

graph and element ids

The generic parameter <ID> in Graph<ID> represents the type for all identifier in the graph. All identifiers for vertices, edges, and the id for the graph must be the same type. Ids must correctly implement equals and hashcode and it is highly suggested that the id be an immutable type. In this example undirected and directed have an optional id that is not set. The id can be passed into the constructor or set by calling the id method.

var undirected = new UndirectedGraph<String>("undirected");
directed.id("directed");

The graph id may also be changed.

graph.id("workflow");

Vertices require and id while an id is optional in for a graph and edges. The id is set when creating a vertex using a vertex method on the Graph object.

graph.vertex("A");
graph.getVertex("B");

As with graphs edges have an optional id which may be set after creating an edge using the getEdge method on the Graph object.

graph.getEdge("A", "B").id("id");

graph and element properties

Graphs, vertices, and edges have support for properties. Each of these objects have property methods which add properties to the object. Here is an example of each.

graph.property("name", "workflow");
graph.getVertex("step1").property("color", "green");
graph.getEdge("step1", "step2").property("color", "red");
graph.getVertex("step2").property("color", "grey");

Properties may be added in groups using the overloaded methods. This is an example using an edge but these methods are supported by graph and vertex as well.

graph.getEdge("step1", "step2").property("queueSize", 10, "type", ArrayBlockingQueue.class);

Properties may also be passed into the graph methods directly. This allows elements to be created with properties all in one method call.

graph.vertex("step1", "color", "red", "action", this::step1);
graph.edge("step1", "step2", "queueSize", 10, "type", ArrayBlockingQueue.class);
graph.vertex("step2", "color", "red", "action", "this::step2);

inherited properties

Vertex and edge elements are able to inherit properties set in the graph. Inherited properties are set by calling the vetexPropety or edgeProperty methods on the graph.

graph.vertexProperty("color", "lightgrey");
graph.edgeProperty("color", "lightgrey");

Inherited properties are returned by an element’s getProperty method if the property was not set on the element. Inherited properties may be overriden by setting the property one the element.

graph.vertexProperty("color", "lightgrey");
graph.getVertex("A").getProperty("color");
graph.getVertex("A").property("color", "green");

It is possible to only view the local properties of an element by calling the local() method or to view the inherited properties by calling inherited().

events

Events are supported using greenrobot’s EventBus. All events are located in the events package. Events are supported by graphs implementing the EventGraph interface. An EventBus needs to be passed into the constructors.

var undirected = new UndirectedEventGraph(bus);
var directed = new DirectedEventGraph(bus);

Creating a graph results in an event. This can be either UndirectedGraphCreated or DirectedGraphCreated being posted to the bus.