Ideas: New API for Graph

make edge and vertex methods fluent (by returning the Graph)

Right now:

Vertex a = graph.vertex("A");
Vertex b = graph.edge("A", "B");

To make this fluent instead of returning a vertex or edge these methods need to return the graph.

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

findVertex and findEdge will still return an Optional for the element so the methods for Vertex and Edge are still visible.

Properties

How can properties be added? If these methods no longer return an element then properties will need to be added using the find methods first. One option is to allow the vertex and edge methods to take a map of properties.

graph.vertex("A", Map.of("color", "blue"));

The problem here is ordering. Graph properties are ordered with a LinkedHashMap so properties can be deterministic and create the same graphviz files. Using Map.of() may break that dependency.

Using a static method to create a LinkedHashMap.

graph.vertex("A", property("color", "blue"))
    .edge("A", "B", property("color", "red", "weight", 10))
    .vertex("B", property("color", "green"));

User can still use Map.of() methods Need to know about this method and import it

Using overloaded methods for entries.

graph.vertex("A", "color", "blue")
    .edge("A", "B", "color", "red", "weight", 10)
    .vertex("B", "color", "green");

Would need to add suppport for Map.of() separately.

Maybe all options should be implemented.

May work for the fluent dsl.

Persistent data structure

Returning graph in these methods will allow for a fluent api but it may also make it possible to create "persistent" graphs which are immutable. This would allow for GraphEvent to pass in the graph so each event subscription can get an immutable snapshot of the graph at that point in time.

The vertex and edge methods in graph would need to become the only way to create new versions of the graph. This would mean the methods in Vertex and Edge which mutate the graph and add properties would need to be removed.

New methods would be needed for changing the vertex id and changing to and from of edges. Methods such as connectsTo may need to be removed from Vertex.

how to change vertex id and edge endpoints

as properties of in vertex and edge methods

graph.edge("A", "B")
  .vertex("A", "id", "C")
  .edge("C", "B", "from", "A")
  .edge("A", "B", "to", "D");

  // change vertex id of A to C and changes all edges to use C endpoint instead of A. A is no longer in graph.
  //changes from back to A. A needs to be created first. C still exists with old properties.
  //changes to endpoint to "D". D is created. B still exists.

This implies that vertex cannot have an "id" property and edge cannot have a "to" or "from" property any longer. Or that these are properties of the elements that must always exist. Should these properties be in the property map?

as fluent method calls

graph.edge("A", "B")
  .vertexChangeId("A", "C")
  .edgeChangeFrom("C", "B", "A")
  .edgeChangeTo("A", "B", "D");

  // change vertex id of A to C and changes all edges to use C endpoint instead of A. A is now C in graph.
  //changes "from" endpoint back to A. A needs to be created first. C still exists.
  //changes "to" endpoint to "D". D is created. B still exists.