org.jgrapht.traverse.AbstractGraphIterator Maven / Gradle / Ivy

Go to download
/*
 * (C) Copyright 2003-2021, by Barak Naveh and Contributors.
 *
 * JGraphT : a free Java graph-theory library
 *
 * See the CONTRIBUTORS.md file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the
 * GNU Lesser General Public License v2.1 or later
 * which is available at
 * http://www.gnu.org/licenses/old-licenses/lgpl-2.1-standalone.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR LGPL-2.1-or-later
 */
package org.jgrapht.traverse;

import org.jgrapht.*;
import org.jgrapht.event.*;

import java.util.*;

/**
 * An empty implementation of a graph iterator to minimize the effort required to implement graph
 * iterators.
 *
 * @param  the graph vertex type
 * @param  the graph edge type
 *
 * @author Barak Naveh
 */
public abstract class AbstractGraphIterator
    implements
    GraphIterator
{
    private final Set> traversalListeners = new LinkedHashSet<>();

    // We keep this cached redundantly with traversalListeners.size()
    // so that subclasses can use it as a fast check to see if
    // event firing calls can be skipped.
    protected int nListeners = 0;

    protected final FlyweightEdgeEvent reusableEdgeEvent;
    protected final FlyweightVertexEvent reusableVertexEvent;
    protected final Graph graph;
    protected boolean crossComponentTraversal;
    protected boolean reuseEvents;

    /**
     * Create a new iterator
     * 
     * @param graph the graph
     */
    public AbstractGraphIterator(Graph graph)
    {
        this.graph = Objects.requireNonNull(graph, "graph must not be null");
        this.reusableEdgeEvent = new FlyweightEdgeEvent<>(this, null);
        this.reusableVertexEvent = new FlyweightVertexEvent<>(this, null);
        this.crossComponentTraversal = true;
        this.reuseEvents = false;
    }

    /**
     * Get the graph being traversed.
     * 
     * @return the graph being traversed
     */
    public Graph getGraph()
    {
        return graph;
    }

    /**
     * Sets the cross component traversal flag - indicates whether to traverse the graph across
     * connected components.
     *
     * @param crossComponentTraversal if true traverses across connected components.
     */
    public void setCrossComponentTraversal(boolean crossComponentTraversal)
    {
        this.crossComponentTraversal = crossComponentTraversal;
    }

    /**
     * Test whether this iterator is set to traverse the graph across connected components.
     *
     * @return true if traverses across connected components, otherwise
     *         false.
     */
    @Override
    public boolean isCrossComponentTraversal()
    {
        return crossComponentTraversal;
    }

    @Override
    public void setReuseEvents(boolean reuseEvents)
    {
        this.reuseEvents = reuseEvents;
    }

    @Override
    public boolean isReuseEvents()
    {
        return reuseEvents;
    }

    @Override
    public void addTraversalListener(TraversalListener l)
    {
        traversalListeners.add(l);
        nListeners = traversalListeners.size();
    }

    @Override
    public void remove()
    {
        throw new UnsupportedOperationException("remove");
    }

    @Override
    public void removeTraversalListener(TraversalListener l)
    {
        traversalListeners.remove(l);
        nListeners = traversalListeners.size();
    }

    /**
     * Informs all listeners that the traversal of the current connected component finished.
     *
     * @param e the connected component finished event.
     */
    protected void fireConnectedComponentFinished(ConnectedComponentTraversalEvent e)
    {
        for (TraversalListener l : traversalListeners) {
            l.connectedComponentFinished(e);
        }
    }

    /**
     * Informs all listeners that a traversal of a new connected component has started.
     *
     * @param e the connected component started event.
     */
    protected void fireConnectedComponentStarted(ConnectedComponentTraversalEvent e)
    {
        for (TraversalListener l : traversalListeners) {
            l.connectedComponentStarted(e);
        }
    }

    /**
     * Informs all listeners that a the specified edge was visited.
     *
     * @param e the edge traversal event.
     */
    protected void fireEdgeTraversed(EdgeTraversalEvent e)
    {
        for (TraversalListener l : traversalListeners) {
            l.edgeTraversed(e);
        }
    }

    /**
     * Informs all listeners that a the specified vertex was visited.
     *
     * @param e the vertex traversal event.
     */
    protected void fireVertexTraversed(VertexTraversalEvent e)
    {
        for (TraversalListener l : traversalListeners) {
            l.vertexTraversed(e);
        }
    }

    /**
     * Informs all listeners that a the specified vertex was finished.
     *
     * @param e the vertex traversal event.
     */
    protected void fireVertexFinished(VertexTraversalEvent e)
    {
        for (TraversalListener l : traversalListeners) {
            l.vertexFinished(e);
        }
    }

    /**
     * Create a vertex traversal event.
     * 
     * @param vertex the vertex
     * @return the event
     */
    protected VertexTraversalEvent createVertexTraversalEvent(V vertex)
    {
        if (reuseEvents) {
            reusableVertexEvent.setVertex(vertex);
            return reusableVertexEvent;
        } else {
            return new VertexTraversalEvent<>(this, vertex);
        }
    }

    /**
     * Create an edge traversal event.
     * 
     * @param edge the edge
     * @return the event
     */
    protected EdgeTraversalEvent createEdgeTraversalEvent(E edge)
    {
        if (isReuseEvents()) {
            reusableEdgeEvent.setEdge(edge);
            return reusableEdgeEvent;
        } else {
            return new EdgeTraversalEvent<>(this, edge);
        }
    }

    /**
     * A reusable edge event.
     *
     * @author Barak Naveh
     */
    static class FlyweightEdgeEvent
        extends
        EdgeTraversalEvent
    {
        private static final long serialVersionUID = 4051327833765000755L;

        /**
         * Creates a new FlyweightEdgeEvent.
         *
         * @param eventSource the source of the event.
         * @param edge the traversed edge.
         */
        public FlyweightEdgeEvent(Object eventSource, E edge)
        {
            super(eventSource, edge);
        }

        /**
         * Sets the edge of this event.
         *
         * @param edge the edge to be set.
         */
        protected void setEdge(E edge)
        {
            this.edge = edge;
        }
    }

    /**
     * A reusable vertex event.
     *
     * @author Barak Naveh
     */
    static class FlyweightVertexEvent
        extends
        VertexTraversalEvent
    {
        private static final long serialVersionUID = 3834024753848399924L;

        /**
         * Creates a new FlyweightVertexEvent.
         *
         * @param eventSource the source of the event.
         * @param vertex the traversed vertex.
         */
        public FlyweightVertexEvent(Object eventSource, V vertex)
        {
            super(eventSource, vertex);
        }

        /**
         * Sets the vertex of this event.
         *
         * @param vertex the vertex to be set.
         */
        protected void setVertex(V vertex)
        {
            this.vertex = vertex;
        }
    }

}