001/*
002 * Copyright 2006 - 2013
003 *     Stefan Balev     <stefan.balev@graphstream-project.org>
004 *     Julien Baudry    <julien.baudry@graphstream-project.org>
005 *     Antoine Dutot    <antoine.dutot@graphstream-project.org>
006 *     Yoann Pigné      <yoann.pigne@graphstream-project.org>
007 *     Guilhelm Savin   <guilhelm.savin@graphstream-project.org>
008 * 
009 * This file is part of GraphStream <http://graphstream-project.org>.
010 * 
011 * GraphStream is a library whose purpose is to handle static or dynamic
012 * graph, create them from scratch, file or any source and display them.
013 * 
014 * This program is free software distributed under the terms of two licenses, the
015 * CeCILL-C license that fits European law, and the GNU Lesser General Public
016 * License. You can  use, modify and/ or redistribute the software under the terms
017 * of the CeCILL-C license as circulated by CEA, CNRS and INRIA at the following
018 * URL <http://www.cecill.info> or under the terms of the GNU LGPL as published by
019 * the Free Software Foundation, either version 3 of the License, or (at your
020 * option) any later version.
021 * 
022 * This program is distributed in the hope that it will be useful, but WITHOUT ANY
023 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
024 * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
025 * 
026 * You should have received a copy of the GNU Lesser General Public License
027 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
028 * 
029 * The fact that you are presently reading this means that you have had
030 * knowledge of the CeCILL-C and LGPL licenses and that you accept their terms.
031 */
032package org.graphstream.graph;
033
034import java.util.Collection;
035import java.util.Iterator;
036
037/**
038 * Structures are generic objects which may contain nodes and edges.
039 * 
040 */
041public interface Structure {
042        /**
043         * Number of nodes in this graph.
044         * 
045         * @return The number of nodes.
046         */
047        int getNodeCount();
048
049        /**
050         * Number of edges in this graph.
051         * 
052         * @return The number of edges.
053         */
054        int getEdgeCount();
055
056        /**
057         * Iterator on the set of nodes, in an undefined order. This method is
058         * implicitly generic and returns an Iterator over something which extends
059         * Node. The return type is the one of the left part of the assignment. For
060         * example, in the following call :
061         * 
062         * <pre>
063         * Iterator&lt;ExtendedNode&gt; ite = graph.getNodeIterator();
064         * </pre>
065         * 
066         * the method will return an Iterator&lt;ExtendedNode&gt;. If no left part
067         * exists, method will just return an Iterator&lt;Node&gt;.
068         * 
069         * @return The iterator.
070         */
071        <T extends Node> Iterator<T> getNodeIterator();
072
073        /**
074         * Iterator on the set of edges, in an undefined order. This method is
075         * implicitly generic and returns an Iterator over something which extends
076         * Edge. The return type is the one of the left part of the assignment. For
077         * example, in the following call :
078         * 
079         * <pre>
080         * Iterator&lt;ExtendedEdge&gt; ite = graph.getEdgeIterator();
081         * </pre>
082         * 
083         * the method will return an Iterator&lt;ExtendedEdge&gt;. If no left part
084         * exists, method will just return an Iterator&lt;Edge&gt;.
085         * 
086         * @return The iterator.
087         */
088        <T extends Edge> Iterator<T> getEdgeIterator();
089
090        /**
091         * Set of nodes usable in a for-each instruction. This method is implicitly
092         * generic and returns an Iterable over something which extends Node. The
093         * return type is the one of the left part of the assignment. For example,
094         * in the following call :
095         * 
096         * <pre>
097         * Iterable&lt;ExtendedNode&gt; ite = struct.getEachNode();
098         * </pre>
099         * 
100         * the method will return an Iterable&lt;ExtendedNode&gt;. If no left part
101         * exists, method will just return an Iterable&lt;Node&gt;. It is possible
102         * to use it in a for-each loop by giving the parameter :
103         * 
104         * <pre>
105         * for (ExtendedNode n : struct.&lt;ExtendedNode&gt; getEachNode()) {
106         *      // ...
107         * }
108         * </pre>
109         * 
110         * @return An "iterable" view of the set of nodes.
111         * @see #getNodeIterator()
112         * @see #getEachNode()
113         */
114        <T extends Node> Iterable<? extends T> getEachNode();
115
116        /**
117         * Set of edges usable in a for-each instruction. This method is implicitly
118         * generic and returns an Iterable over something which extends Edge. The
119         * return type is the one of the left part of the assignment. For example,
120         * in the following call :
121         * 
122         * <pre>
123         * Iterable&lt;ExtendedNEdge&gt; ite = struct.getEachEdge();
124         * </pre>
125         * 
126         * the method will return an Iterable&lt;ExtendedEdge&gt;. If no left part
127         * exists, method will just return an Iterable&lt;Edge&gt;. It is possible
128         * to use it in a for-each loop by giving the parameter :
129         * 
130         * <pre>
131         * for (ExtendedEdge e : struct.&lt;ExtendedEdge&gt; getEachEdge()) {
132         *      // ...
133         * }
134         * </pre>
135         * 
136         * @return An "iterable" view of the set of edges.
137         * @see #getEdgeIterator()
138         * @see #getEdgeSet()
139         */
140        <T extends Edge> Iterable<? extends T> getEachEdge();
141
142        /**
143         * Unmodifiable view of the set of nodes. This method is implicitly generic
144         * and returns a Collection of something which extends Node. The return type
145         * is the one of the left part of the assignment. For example, in the
146         * following call :
147         * 
148         * <pre>
149         * Collection&lt;ExtendedNode&gt; c = struct.getNodeSet();
150         * </pre>
151         * 
152         * the method will return a Collection&lt;ExtendedNode&gt;. If no left part
153         * exists, method will just return a Collection&lt;Node&gt;.
154         * 
155         * @return A set of nodes that can only be read, not changed.
156         * @see #getNodeIterator()
157         * @see #getEachNode()
158         */
159        <T extends Node> Collection<T> getNodeSet();
160
161        /**
162         * Unmodifiable view of the set of edges. This method is implicitly generic
163         * and returns a Collection of something which extends Edge. The return type
164         * is the one of the left part of the assignment. For example, in the
165         * following call :
166         * 
167         * <pre>
168         * Collection&lt;ExtendedEdge&gt; c = struct.getEdgeSet();
169         * </pre>
170         * 
171         * the method will return a Collection&lt;ExtendedEdge&gt;. If no left part
172         * exists, method will just return a Collection&lt;Edge&gt;.
173         * 
174         * @return A set of edges that can only be read, not changed.
175         * @see #getEdgeIterator()
176         * @see #getEachEdge()
177         */
178        <T extends Edge> Collection<T> getEdgeSet();
179}