GraphModel.java

   /*
Copyright 2008-2010 Gephi
Authors : Mathieu Bastian <mathieu.bastian@gephi.org>
Website : http://www.gephi.org

This file is part of Gephi.

Gephi is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

Gephi is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with Gephi.  If not, see <http://www.gnu.org/licenses/>.
 */
package org.gephi.graph.api;

import org.gephi.project.api.Workspace;

/**
 * Root interface that contains the complete graph structure and build
 * {@link Graph} objets on demand.
 * <p>
 * The graph structure contains several views. {@link GraphView} are sub-graphs with a unique
 * identifier, the <b>viewId</b>. The model maintains all views, and especially:
 * <ul><li><b>The Main View:</b> The complete graph, with a view id equal to zero.</li>
 * <li><b>The Visible View:</b> The graph currently visualized. Can be the main view
 * or an other view that expose a particular sub-graph.</li></ul>
 * Different type of graph can be queried: <b>directed</b>,
 * <b>undirected</b>, <b>mixed</b> and <b>hierarchical</b>. All types can be queried
 * at any time, regardless how the structure is. Indeed even if only directed edges
 * were appened to the graph, an <b>undirected</b> graph can be obtained.
 * <p>
 * It is preferable to use the main graph for performing updates (add, remove, ...).
 * <p>
 * <h3>Append data to an empty model</h3>
 * The following code shows how to add two nodes an an edge to graph.
 * <pre>
 * Graph graph = model.getGraph();
 * Node n1 = model.factory().newNode();
 * Node n2 = model.factory().newNode();
 * Edge e1 = model.factory().newEdge(n1, n2);
 * graph.addNode(n1);
 * graph.addNode(n2);
 * graph.addEdge(e1);
 * </pre>
 * <h3>Set Visible view</h3>
 * The following code shows how to set the visible view. This is useful if you
 * need to visualize a sub-graph.
 * <pre>
 * GraphView newView = model.newView();     //Duplicate main view
 * Graph subGraph = model.getGraph(newView);
 * //Filter subgraph by removing nodes and edges
 * model.setVisibleView(newView);       //Set the view as current visible view
 * </pre>
 * <b>Note:</b> Pay attention to destroy views when they are not used anymore.
 * @author Mathieu Bastian
 * @see GraphController
 */
public interface GraphModel {

    /**
     * Returns the factory that creates nodes and edges for this model.
     * @return      the graph model factory
     */
    public GraphFactory factory();

    /**
     * Returns the model settings.
     * @return      the graph model settings
     */
    public GraphSettings settings();

    /**
     * Create a new view by duplicating <b>main</b> view. The view contains all
     * nodes and edges in the structure.
     * @return      a new graph view, obtained from duplicating main view
     */
    public GraphView newView();

    /**
     * Copy <code>view</code> to a new graph view. The new view contains all
     * nodes and edges present in <code>view</code>.
     * @return  a new graph view, obtained from duplicating <code>view</code>
     */
    public GraphView copyView(GraphView view);

    /**
     * Destroy <code>view</code>, if exists. Always destroy views that are not
     * needed anymore to avoid memory overhead.
     * @param view  the view that is to be destroyed
     */
    public void destroyView(GraphView view);

    /**
     * Sets the current visible view and nofity listeners the visible view changed.
     * @param view  the view that is to be set as the visible view
     */
    public void setVisibleView(GraphView view);

    /**
     * Returns the current viisble view. By default, returns the <b>main</b>
     * view.
     * @return      the current visible view
     */
    public GraphView getVisibleView();

    /**
     * Build a <code>Graph</code> to access the <b>main</b> view. If no undirected
     * edges have been added, returns a <code>DirectedGraph</code>. If the graph
     * only contains undirected edges, returns a <code>UndirectedGraph</code>.
     * If both directed and undirected edges exists, returns a <code>MixedGraph</code>.
     * @return      a graph object, directed by default
     */
    public Graph getGraph();

    /**
     * Build a <code>DirectedGraph</code> to access the <b>main</b> view.
     * @return      a directed graph object
     */
    public DirectedGraph getDirectedGraph();

    /**
     * Build a <code>UndirectedGraph</code> to access the <b>main</b> view.
     * @return      an undirected graph object
     */
    public UndirectedGraph getUndirectedGraph();

    /**
     * Build a <code>MixedGraph</code> to access the <b>main</b> view.
     * @return      a mixed graph object
     */
    public MixedGraph getMixedGraph();

    /**
     * Build a <code>HierarchicalGraph</code> to access the <b>main</b> view.
     * If no undirected edges have been added, returns a
     * <code>HierarchicalDirectedGraph</code>. If the graph only contains undirected
     * edges, returns a <code>HierarchicalUndirectedGraph</code>. If both directed
     * and undirected edges exists, returns a <code>HierarchicalMixedGraph</code>.
     * <p>
     * Hierarchical graphs are normal graphs with more features to handle graphs
     * within graphs.
     * @return      a hierarchical graph object, directed by default
     */
    public HierarchicalGraph getHierarchicalGraph();

    /**
     * Build a <code>HierarchicalDirectedGraph</code> to access the <b>main</b> view.
     * @return      a hierarchical directed graph object
     */
    public HierarchicalDirectedGraph getHierarchicalDirectedGraph();

    /**
     * Build a <code>HierarchicalUndirectedGraph</code> to access the <b>main</b> view.
     * @return      a hierarchical undirected graph object
     */
    public HierarchicalUndirectedGraph getHierarchicalUndirectedGraph();

    /**
     * Build a <code>HierarchicalMixedGraph</code> to access the <b>main</b> view.
     * @return      a hierarchical mixed graph object
     */
    public HierarchicalMixedGraph getHierarchicalMixedGraph();

    /**
     * Build a <code>Graph</code> to access the <b>visible</b> view. If no undirected
     * edges have been added, returns a <code>DirectedGraph</code>. If the graph
     * only contains undirected edges, returns a <code>UndirectedGraph</code>.
     * If both directed and undirected edges exists, returns a <code>MixedGraph</code>.
     * @return      a graph object, directed by default
     */
    public Graph getGraphVisible();

    /**
     * Build a <code>DirectedGraph</code> to access the <b>visible</b> view.
     * @return      a directed graph object
     */
    public DirectedGraph getDirectedGraphVisible();

    /**
     * Build a <code>UndirectedGraph</code> to access the <b>visible</b> view.
     * @return      an undirected graph object
     */
    public UndirectedGraph getUndirectedGraphVisible();

    /**
     * Build a <code>MixedGraph</code> to access the <b>visible</b> view.
     * @return      a mixed graph object
     */
    public MixedGraph getMixedGraphVisible();

    /**
     * Build a <code>HierarchicalGraph</code> to access the <b>visible</b> view.
     * If no undirected edges have been added, returns a
     * <code>HierarchicalDirectedGraph</code>. If the graph only contains undirected
     * edges, returns a <code>HierarchicalUndirectedGraph</code>. If both directed
     * and undirected edges exists, returns a <code>HierarchicalMixedGraph</code>.
     * <p>
     * Hierarchical graphs are normal graphs with more features to handle graphs
     * within graphs.
     * @return      a hierarchical graph object, directed by default
     */
    public HierarchicalGraph getHierarchicalGraphVisible();

    /**
     * Build a <code>HierarchicalDirectedGraph</code> to access the <b>visible</b> view.
     * @return      a hierarchical directed graph object
     */
    public HierarchicalDirectedGraph getHierarchicalDirectedGraphVisible();

    /**
     * Build a <code>HierarchicalUndirectedGraph</code> to access the <b>visible</b> view.
     * @return      a hierarchical undirected graph object
     */
    public HierarchicalUndirectedGraph getHierarchicalUndirectedGraphVisible();

    /**
     * Build a <code>HierarchicalMixedGraph</code> to access the <b>visible</b> view.
     * @return      a hierarchical mixed graph object
     */
    public HierarchicalMixedGraph getHierarchicalMixedGraphVisible();

    /**
     * Build a <code>Graph</code> to access <code>view/code>. If no undirected
     * edges have been added, returns a <code>DirectedGraph</code>. If the graph
     * only contains undirected edges, returns a <code>UndirectedGraph</code>.
     * If both directed and undirected edges exists, returns a <code>MixedGraph</code>.
     * @return      a graph object on <code>view</code>, directed by default
     */
    public Graph getGraph(GraphView view);

    /**
     * Build a <code>DirectedGraph</code> to access <code>view</code>.
     * @return      a directed graph object on <code>view</code>
     */
    public DirectedGraph getDirectedGraph(GraphView view);

    /**
     * Build a <code>UndirectedGraph</code> to access <code>view</code>.
     * @return      an undirected graph object on <code>view</code>
     */
    public UndirectedGraph getUndirectedGraph(GraphView view);

    /**
     * Build a <code>MixedGraph</code> to access <code>view</code>.
     * @return      a mixed graph object on <code>view</code>
     */
    public MixedGraph getMixedGraph(GraphView view);

    /**
     * Build a <code>HierarchicalGraph</code> to access <code>view</code>.
     * If no undirected edges have been added, returns a
     * <code>HierarchicalDirectedGraph</code>. If the graph only contains undirected
     * edges, returns a <code>HierarchicalUndirectedGraph</code>. If both directed
     * and undirected edges exists, returns a <code>HierarchicalMixedGraph</code>.
     * <p>
     * Hierarchical graphs are normal graphs with more features to handle graphs
     * within graphs.
     * @return      a hierarchical graph object on <code>view</code>, directed by default
     */
    public HierarchicalGraph getHierarchicalGraph(GraphView view);

    /**
     * Build a <code>HierarchicalDirectedGraph</code> to access <code>view</code>.
     * @return      a hierarchical directed graph object on <code>view</code>
     */
    public HierarchicalDirectedGraph getHierarchicalDirectedGraph(GraphView view);

    /**
     * Build a <code>HierarchicalUndirectedGraph</code> to access <code>view</code>.
     * @return      a hierarchical undirected graph object on <code>view</code>
     */
    public HierarchicalUndirectedGraph getHierarchicalUndirectedGraph(GraphView view);

    /**
     * Build a <code>HierarchicalMixedGraph</code> to access <code>view</code>.
     * @return      a hierarchical mixed graph object on <code>view</code>
     */
    public HierarchicalMixedGraph getHierarchicalMixedGraph(GraphView view);

    /**
     * Copy the graph structure from <code>graph</code> to this model. The
     * given <code>graph</code>must come from a different <code>GraphModel</code>,
     * e.g. a different workspace.
     * @param graph the graph that is to be copied in this model
     * @throws IllegalArgumentException if <code>graph</code> belongs to this
     * graph model
     */
    public void pushFrom(Graph graph);

    /**
     * Copy the nodes and edges betweeen these nodes from the <code>graph</code>
     * to this model. The given <code>graph</code>must come from a different
     * <code>GraphModel</code>, e.g. a different workspace.
     * @param graph the graph that is to be copied in this model
     * @param nodes the nodes to copy
     * @throws IllegalArgumentException if <code>graph</code> belongs to this
     * graph model
     */
    public void pushNodes(Graph graph, Node[] nodes);

    /**
     * Returns a complete copy of this model, including all views but not listeners.
     * @return      a copy of this graph model
     */
    public GraphModel copy();

    /**
     * Clears the model by deleting all views and reseting <code>main</code>
     * view. Calling this method immediately makes all <code>Graph</code> on
     * other views than <b>main</b> obsolete.
     */
    public void clear();

    /**
     * Add <code>graphListener</code> as a listener to this graph, if it is not already.
     * To pass a <code>WeakReference</code>, use Netbeans <code>WeakListeners</code> utility class.
     * @param graphListener the listener to add
     */
    public void addGraphListener(GraphListener graphListener);

    /**
     * Remove <code>graphListener</code> as a listener to this graph.
     * @param graphListener the listener to remove
     */
    public void removeGraphListener(GraphListener graphListener);

    /**
     * Returns <code>true</code> if the graph is <b>directed</b> by default. This value is an
     * indicator of the current state and it means that so far all edges are directed in the graph.
     * @return <code>true</code> if the graph is only directed or <code>false</code> otherwise
     * @see DirectedGraph
     */
    public boolean isDirected();

    /**
     * Returns <code>true</code> if the graph is <b>undirected</b> by default. This value is an
     * indicator of the current state and it means that so far all edges are undirected in the graph.
     * @return <code>true</code> if the graph is only undirected or <code>false</code> otherwise
     * @see UndirectedGraph
     */
    public boolean isUndirected();

    /**
     * Returns <code>true</code> if the graph is <b>mixed</b> by default. This value is an
     * indicator of the current state and it means that directed and undirected edges has been
     * added to the graph. When it returns <code>true</code>, <code>isDirected()</code> and
     * <code>isUndirected()</code> methods always returns <code>false</code>.
     * @return <code>true</code> if the graph is mixed or <code>false</code> otherwise
     * @see MixedGraph
     */
    public boolean isMixed();

    /**
     * Returns <code>true</code> if the graph is <b>hierarchical</b>. This indicates the presence
     * of a hierarchy, in other words the height of the tree is greater than 0.
     * @return <code>true</code> if the graph is clustered or <code>false</code> otherwise
     * @see HierarchicalGraph
     */
    public boolean isHierarchical();

    /**
     * Returns the workspace this graph model belongs to.
     * @return the workspace that owns this graph model
     */
    public Workspace getWorkspace();
}