Package com.mastfrog.graph.dynamic

Class 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 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:

      • 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

      • 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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode 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