DynamicGraph (graph 2.7.2 API)

java.lang.Object
- com.mastfrog.graph.dynamic.DynamicGraph<T>

All Implemented Interfaces:

ObjectGraph<T>
```
public class DynamicGraph<T>
extends Object
implements ObjectGraph<T>
```
Implements ObjectGraph over a snapshot which can be recomputed when updated - useful for implementing dynamic graphs whose contents change occasionally but rarely. Can be stored to a file channel. Internally, uses a non-fair read/write lock to manage thread-safe updates. Delegates to a graph instance which is created on-demand and retained until the next modification.

Author:

Tim Boudreau

Constructor Summary

Constructors
Constructor and Description
`DynamicGraph()` Create a graph with the default initial capacity of 128.
`DynamicGraph(int targetSize)` Create a graph with the passed initial capacity.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`addEdge(T depender, T dependee)` Ad an edge from one node to another.
`List<Score<T>>`	`apply(RankingAlgorithm<?> alg)`
`Set<T>`	`bottomLevelNodes()` Get the set of nodes which have no outbound edges.
`List<T>`	`byClosureSize()` Get a list of the nodes in the graph sorted by the size of their closure.
`List<T>`	`byReverseClosureSize()` Get a list of the nodes in the graph sorted by the size of their reverse closure (all paths to the top of the graph from this node).
`Set<T>`	`children(T node)` Get the set of string node names which are immediate child nodes of a given one (if the graph is cyclic, this may include the node name passed).
`void`	`clear()` Clear the contents of the graph.
`Set<T>`	`closureOf(T node)` Get the closure of this node in the graph - all nodes which are reachable following outbound edges from this node and its descendants.
`int`	`closureSize(T node)` Determine the size of the closure of this node, following outbound edges to the bottom of the graph, traversing each node once.
`boolean`	`contains(T item)` Determine if this graph contains the item passed.
`Set<T>`	`disjunctionOfClosureOfHighestRankedNodes()` This requires some explaining - it is used to pick the initial set of colorings that are active - attempting to find nodes that are likely to be ones someone would want flagged.
`int`	`distance(T a, T b)` Get the distance along the shortest path between two node.
`Set<String>`	`edgeStrings()` For logging convenience, get a list of strings that identify the edges present in this graph.
`List<Score<T>>`	`eigenvectorCentrality()` Compute the eigenvector centrality - "most likely to be connected through" - score for each node.
`boolean`	`equals(Object obj)`
`boolean`	`hasEdge(T depender, T dependee)` Determine if an outbound edge is present from depender to dependee.
`int`	`hashCode()`
`int`	`inboundReferenceCount(T node)` Count the number of nodes that have outbound edges to the passed node.
`boolean`	`isUnreferenced(T node)` Returns true if this node has no inbound edges.
`static <C extends WritableByteChannel & SeekableByteChannel,T> DynamicGraph<T>`	`load(C channel, IOFunction<ByteBuffer,T> func)` Load a graph from a FileChannel or similar.
`ObjectGraph<T>`	`omitting(Set<T> items)` Create a copy of this graph, omitting the passed set of items.
`int`	`outboundReferenceCount(T node)` Count the number of nodes this node has outbound edges to.
`List<Score<T>>`	`pageRank()` Compute the pagerank score of every node in the graph.
`Set<T>`	`parents(T node)` Get the set of strings which are immediate parent nodes to a given one (if the graph is cyclic, this may include the node name passed).
`List<ObjectPath<T>>`	`pathsBetween(T a, T b)` Get the set of paths that exist between two nodes.
`static BitSet`	`readBitSet(ByteBuffer buffer, int limit)`
`boolean`	`removeAllReferencesTo(T item)` Remove an item and all edges connected to it from the graph.
`boolean`	`removeEdge(T depender, T dependee)` Remove an edge between two items.
`Set<T>`	`reverseClosureOf(T node)` Get the reverse closure of a node in the graph - all nodes which have an outbound edge to this node, and all nodes which have an outbound edge to one of those, and so forth, to the top of the graph.
`int`	`reverseClosureSize(T node)` Determine the size of the inverse closure of this node, following inbound edges to the top of the graph, traversing each node once.
`int`	`revision()` Get the number of changes that have been made to this graph since its creation; typically used to determine if the graph has changed since some computation was performed.
`void`	`save(ObjectOutput out)` Optimized serialization support.
`boolean`	`setOutboundEdges(T item, Set<T> dependencies)` Set the outbound edges from an item, removing any edges that previously existed which are not present in the passed set.
`int`	`size()` Returns the number of items belonging to this graph.
`<C extends WritableByteChannel & SeekableByteChannel> void`	`store(C channel, IOToIntBiFunction<T,C> itemWriter)` Store this graph to a FileChannel or similar.
`void`	`toIntGraph(BiConsumer<IndexedResolvable<? extends T>,IntGraph> consumer)` Convert this graph to its (usually internal) IntGraph, needed for serialization.
`T`	`toNode(int index)` Get the node for an index.
`int`	`toNodeId(T name)` Get the integer id used internally for a node.
`Set<T>`	`topLevelOrOrphanNodes()` Get the set of nodes which have no inbound edges.
`List<T>`	`topologicalSort(Set<T> items)` Topologically sort a set of items; note that if a graph contains cycles, topological sorting is impossible - you will get some order that roughly approximates a topological sort for any items that are not part of a cycle; the order of appearance of items that participate in cycles is implementation-dependent.
`String`	`toString()`
`void`	`walk(ObjectGraphVisitor<? super T> v)` Walk the tree of nodes in some order, such that each node is only visited once.
`void`	`walk(T startingWith, ObjectGraphVisitor<? super T> v)` Walk the tree of node definitions and node references in some order, starting from the passed starting node.
`void`	`walkUpwards(T startingWith, ObjectGraphVisitor<? super T> v)` Walk the antecedents of a node.
`static <C extends WritableByteChannel & SeekableByteChannel> int`	`writeBitSet(BitSet set, C channel, ByteBuffer numBuffer)`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - DynamicGraph
```
public DynamicGraph()
```
    Create a graph with the default initial capacity of 128.
  - DynamicGraph
```
public DynamicGraph(int targetSize)
```
    Create a graph with the passed initial capacity.
    
    Parameters:
    
    targetSize -
- Method Detail
  - toIntGraph
```
public void toIntGraph(BiConsumer<IndexedResolvable<? extends T>,IntGraph> consumer)
```
    Description copied from interface: ObjectGraph
    
    Convert this graph to its (usually internal) IntGraph, needed for serialization.
    
    Specified by:
    
    toIntGraph in interface ObjectGraph<T>
    
    Parameters:
    
    consumer - A consumer that takes the list of items and the graph.
  - omitting
```
public ObjectGraph<T> omitting(Set<T> items)
```
    Description copied from interface: ObjectGraph
    
    Create a copy of this graph, omitting the passed set of items.
    
    Specified by:
    
    omitting in interface ObjectGraph<T>
    
    Parameters:
    
    items - The items to omit
    
    Returns:
    
    A new graph
  - size
```
public int size()
```
    Returns the number of items belonging to this graph.
    
    Specified by:
    
    size in interface ObjectGraph<T>
    
    Returns:
    
    The count
  - contains
```
public boolean contains(T item)
```
    Determine if this graph contains the item passed.
    
    Parameters:
    
    item - The item
    
    Returns:
    
    true if it is present
  - revision
```
public int revision()
```
    Get the number of changes that have been made to this graph since its creation; typically used to determine if the graph has changed since some computation was performed.
    
    Returns:
    
    The revision
  - clear
```
public void clear()
```
    Clear the contents of the graph.
  - setOutboundEdges
```
public boolean setOutboundEdges(T item,
                                Set<T> dependencies)
```
    Set the outbound edges from an item, removing any edges that previously existed which are not present in the passed set.
    
    Parameters:
    
    item -
    
    dependencies -
    
    Returns:
  - addEdge
```
public boolean addEdge(T depender,
                       T dependee)
```
    Ad an edge from one node to another. Self-edges are ignored.
    
    Parameters:
    
    depender - The first item
    
    dependee - The second item
    
    Returns:
    
    True if a new edge was created
  - removeAllReferencesTo
```
public boolean removeAllReferencesTo(T item)
```
    Remove an item and all edges connected to it from the graph.
    
    Parameters:
    
    item - An item
    
    Returns:
    
    true if the graph was changed
  - removeEdge
```
public boolean removeEdge(T depender,
                          T dependee)
```
    Remove an edge between two items.
    
    Parameters:
    
    depender - The item with the outbound edge
    
    dependee - The item with the inbound edge
    
    Returns:
    
    true if the graph changed
  - hasEdge
```
public boolean hasEdge(T depender,
                       T dependee)
```
    Determine if an outbound edge is present from depender to dependee.
    
    Parameters:
    
    depender - One node
    
    dependee - Another node
    
    Returns:
    
    whether the edge exists
  - byClosureSize
```
public List<T> byClosureSize()
```
    Description copied from interface: ObjectGraph
    
    Get a list of the nodes in the graph sorted by the size of their closure.
    
    Specified by:
    
    byClosureSize in interface ObjectGraph<T>
    
    Returns:
    
    A list of string node names
  - byReverseClosureSize
```
public List<T> byReverseClosureSize()
```
    Description copied from interface: ObjectGraph
    
    Get a list of the nodes in the graph sorted by the size of their reverse closure (all paths to the top of the graph from this node).
    
    Specified by:
    
    byReverseClosureSize in interface ObjectGraph<T>
    
    Returns:
    
    A list of string node names
  - edgeStrings
```
public Set<String> edgeStrings()
```
    Description copied from interface: ObjectGraph
    
    For logging convenience, get a list of strings that identify the edges present in this graph.
    
    Specified by:
    
    edgeStrings in interface ObjectGraph<T>
    
    Returns:
  - parents
```
public Set<T> parents(T node)
```
    Description copied from interface: ObjectGraph
    
    Get the set of strings which are immediate parent nodes to a given one (if the graph is cyclic, this may include the node name passed).
    
    Specified by:
    
    parents in interface ObjectGraph<T>
    
    Parameters:
    
    node - A node name
    
    Returns:
    
    The set of parents
  - children
```
public Set<T> children(T node)
```
    Description copied from interface: ObjectGraph
    
    Get the set of string node names which are immediate child nodes of a given one (if the graph is cyclic, this may include the node name passed).
    
    Specified by:
    
    children in interface ObjectGraph<T>
    
    Parameters:
    
    node - The node name
    
    Returns:
    
    A set of child node names
  - inboundReferenceCount
```
public int inboundReferenceCount(T node)
```
    Description copied from interface: ObjectGraph
    
    Count the number of nodes that have outbound edges to the passed node. Will be zero if it has none.
    
    Specified by:
    
    inboundReferenceCount in interface ObjectGraph<T>
    
    Parameters:
    
    node - The node name
    
    Returns:
    
    A count of edges
  - outboundReferenceCount
```
public int outboundReferenceCount(T node)
```
    Description copied from interface: ObjectGraph
    
    Count the number of nodes this node has outbound edges to.
    
    Specified by:
    
    outboundReferenceCount in interface ObjectGraph<T>
    
    Parameters:
    
    node - The node name
    
    Returns:
    
    A count of edges
  - topLevelOrOrphanNodes
```
public Set<T> topLevelOrOrphanNodes()
```
    Description copied from interface: ObjectGraph
    
    Get the set of nodes which have no inbound edges.
    
    Specified by:
    
    topLevelOrOrphanNodes in interface ObjectGraph<T>
    
    Returns:
    
    A set of node names
  - bottomLevelNodes
```
public Set<T> bottomLevelNodes()
```
    Description copied from interface: ObjectGraph
    
    Get the set of nodes which have no outbound edges.
    
    Specified by:
    
    bottomLevelNodes in interface ObjectGraph<T>
    
    Returns:
    
    A set of nodes
  - isUnreferenced
```
public boolean isUnreferenced(T node)
```
    Description copied from interface: ObjectGraph
    
    Returns true if this node has no inbound edges.
    
    Specified by:
    
    isUnreferenced in interface ObjectGraph<T>
    
    Parameters:
    
    node - A node
    
    Returns:
    
    Whether or not it has inbound edges
  - closureSize
```
public int closureSize(T node)
```
    Description copied from interface: ObjectGraph
    
    Determine the size of the closure of this node, following outbound edges to the bottom of the graph, traversing each node once.
    
    Specified by:
    
    closureSize in interface ObjectGraph<T>
    
    Parameters:
    
    node - A node
    
    Returns:
    
    The size of its closure
  - reverseClosureSize
```
public int reverseClosureSize(T node)
```
    Description copied from interface: ObjectGraph
    
    Determine the size of the inverse closure of this node, following inbound edges to the top of the graph, traversing each node once.
    
    Specified by:
    
    reverseClosureSize in interface ObjectGraph<T>
    
    Returns:
  - reverseClosureOf
```
public Set<T> reverseClosureOf(T node)
```
    Description copied from interface: ObjectGraph
    
    Get the reverse closure of a node in the graph - all nodes which have an outbound edge to this node, and all nodes which have an outbound edge to one of those, and so forth, to the top of the graph.
    
    Specified by:
    
    reverseClosureOf in interface ObjectGraph<T>
    
    Parameters:
    
    node - A node name
    
    Returns:
    
    A set of nodes
  - closureOf
```
public Set<T> closureOf(T node)
```
    Description copied from interface: ObjectGraph
    
    Get the closure of this node in the graph - all nodes which are reachable following outbound edges from this node and its descendants.
    
    Specified by:
    
    closureOf in interface ObjectGraph<T>
    
    Parameters:
    
    node - A node name
    
    Returns:
    
    A set of nodes
  - walk
```
public void walk(ObjectGraphVisitor<? super T> v)
```
    Description copied from interface: ObjectGraph
    
    Walk the tree of nodes in some order, such that each node is only visited once.
    
    Specified by:
    
    walk in interface ObjectGraph<T>
    
    Parameters:
    
    v - A visitor
  - walk
```
public void walk(T startingWith,
                 ObjectGraphVisitor<? super T> v)
```
    Description copied from interface: ObjectGraph
    
    Walk the tree of node definitions and node references in some order, starting from the passed starting node.
    
    Specified by:
    
    walk in interface ObjectGraph<T>
    
    Parameters:
    
    startingWith - The starting node
    
    v - A visitor
  - walkUpwards
```
public void walkUpwards(T startingWith,
                        ObjectGraphVisitor<? super T> v)
```
    Description copied from interface: ObjectGraph
    
    Walk the antecedents of a node.
    
    Specified by:
    
    walkUpwards in interface ObjectGraph<T>
    
    Parameters:
    
    startingWith - The starting node
    
    v - A visitor
  - distance
```
public int distance(T a,
                    T b)
```
    Description copied from interface: ObjectGraph
    
    Get the distance along the shortest path between two node.
    
    Specified by:
    
    distance in interface ObjectGraph<T>
    
    Parameters:
    
    a - One node
    
    b - Another node
    
    Returns:
    
    the distance
  - eigenvectorCentrality
```
public List<Score<T>> eigenvectorCentrality()
```
    Description copied from interface: ObjectGraph
    
    Compute the eigenvector centrality - "most likely to be connected *through*" - score for each node. This finds nodes which are most critical - connectors - in the node graph.
    
    Specified by:
    
    eigenvectorCentrality in interface ObjectGraph<T>
    
    Returns:
  - pageRank
```
public List<Score<T>> pageRank()
```
    Description copied from interface: ObjectGraph
    
    Compute the pagerank score of every node in the graph.
    
    Specified by:
    
    pageRank in interface ObjectGraph<T>
    
    Returns:
  - disjunctionOfClosureOfHighestRankedNodes
```
public Set<T> disjunctionOfClosureOfHighestRankedNodes()
```
    Description copied from interface: ObjectGraph
    
    This requires some explaining - it is used to pick the initial set of colorings that are active - attempting to find nodes that are likely to be ones someone would want flagged. The algorithm is this: Rank the nodes according to their pagerank. That typically gets important but common grammar elements such as "expression" or "arguments". Take the top third of those nodes - these will be the most connected to nodes. Then take the closure of each of those - the set of nodes it or nodes it calls touches, and xor them to get the disjunction of their closures. That gives you those nodes which are called indirectly or directly by *one* of the highly ranked nodes, but none of the others. These have a decent chance of being unique things one would like distinct syntax highlighting for.
    
    Specified by:
    
    disjunctionOfClosureOfHighestRankedNodes in interface ObjectGraph<T>
    
    Returns:
  - save
```
public void save(ObjectOutput out)
          throws IOException
```
    Description copied from interface: ObjectGraph
    
    Optimized serialization support.
    
    Specified by:
    
    save in interface ObjectGraph<T>
    
    Parameters:
    
    out - The output
    
    Throws:
    
    IOException - If something goes wrong
  - toNodeId
```
public int toNodeId(T name)
```
    Description copied from interface: ObjectGraph
    
    Get the integer id used internally for a node.
    
    Specified by:
    
    toNodeId in interface ObjectGraph<T>
    
    Parameters:
    
    name - A node
    
    Returns:
    
    An index or -1
  - toNode
```
public T toNode(int index)
```
    Description copied from interface: ObjectGraph
    
    Get the node for an index.
    
    Specified by:
    
    toNode in interface ObjectGraph<T>
    
    Parameters:
    
    index - The index
    
    Returns:
    
    A node
  - apply
```
public List<Score<T>> apply(RankingAlgorithm<?> alg)
```
    Specified by:
    
    apply in interface ObjectGraph<T>
  - pathsBetween
```
public List<ObjectPath<T>> pathsBetween(T a,
                                        T b)
```
    Description copied from interface: ObjectGraph
    
    Get the set of paths that exist between two nodes.
    
    Specified by:
    
    pathsBetween in interface ObjectGraph<T>
    
    Parameters:
    
    a - A first node
    
    b - A second node
    
    Returns:
    
    The paths
  - topologicalSort
```
public List<T> topologicalSort(Set<T> items)
```
    Description copied from interface: ObjectGraph
    
    Topologically sort a set of items; note that if a graph contains cycles, topological sorting is impossible - you will get some order that roughly approximates a topological sort for any items that are not part of a cycle; the order of appearance of items that participate in cycles is implementation-dependent.
    
    Specified by:
    
    topologicalSort in interface ObjectGraph<T>
    
    Parameters:
    
    items - some items
    
    Returns:
    
    A list
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - load
```
public static <C extends WritableByteChannel & SeekableByteChannel,T> DynamicGraph<T> load(C channel,
                                                                                           IOFunction<ByteBuffer,T> func)
                                                                                    throws IOException
```
    Load a graph from a FileChannel or similar.
    
    Type Parameters:
    
    C - The channel type
    
    T - The item type
    
    Parameters:
    
    channel - The channel
    
    func - A function which can read one element of type T from a ByteBuffer, leaving it positioned at the first byte subsequent to the item
    
    Returns:
    
    A graph
    
    Throws:
    
    IOException - If something goes wrong
  - store
```
public <C extends WritableByteChannel & SeekableByteChannel> void store(C channel,
                                                                        IOToIntBiFunction<T,C> itemWriter)
                                                                 throws IOException
```
    Store this graph to a FileChannel or similar.
    
    Type Parameters:
    
    C - The channel type
    
    Parameters:
    
    channel - The channel
    
    itemWriter - A function which can write one item of type T to a channel, leaving the channel's position immediately after the last byte written, and returning the exact number of bytes the function wrote (typical is to serialize the item to a byte array, write the length and then the item bytes)
    
    Throws:
    
    IOException - If something goes wrong
  - readBitSet
```
public static BitSet readBitSet(ByteBuffer buffer,
                                int limit)
                         throws IOException
```
    Throws:
    
    IOException
  - writeBitSet
```
public static <C extends WritableByteChannel & SeekableByteChannel> int writeBitSet(BitSet set,
                                                                                    C channel,
                                                                                    ByteBuffer numBuffer)
                                                                             throws IOException
```
    Throws:
    
    IOException

Class DynamicGraph<T>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DynamicGraph

DynamicGraph

Method Detail

toIntGraph

omitting

size

contains

revision

clear

setOutboundEdges

addEdge

removeAllReferencesTo

removeEdge

hasEdge

byClosureSize

byReverseClosureSize

edgeStrings

parents

children

inboundReferenceCount

outboundReferenceCount

topLevelOrOrphanNodes

bottomLevelNodes

isUnreferenced

closureSize

reverseClosureSize

reverseClosureOf

closureOf

walk

walk

walkUpwards

distance

eigenvectorCentrality

pageRank

disjunctionOfClosureOfHighestRankedNodes

save

toNodeId

toNode

apply

pathsBetween

topologicalSort

equals

hashCode

toString

load

store

readBitSet

writeBitSet