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
034/**
035 * A general purpose class that provides methods for the management of edges in
036 * a graph.
037 * 
038 * <h3>Important</h3> Implementing classes may indicate the complexity of their
039 * implementation of the methods with the <code>complexity</code> tag.
040 * 
041 * @since July 12 2007
042 */
043public interface Edge extends Element {
044        /**
045         * Is the edge directed ?.
046         * 
047         * @return True if the edge is directed.
048         */
049        boolean isDirected();
050
051        /**
052         * Does the source and target of this edge identify the same node ?.
053         * 
054         * @return True if this edge is a loop.
055         */
056        boolean isLoop();
057        
058        /**
059         * First node of the edge.
060         * <p>
061         * This is equivalent to the {@link #getSourceNode()} method, but may be
062         * clearer in the source code if the graph you are using is not directed.
063         * </p>
064         * <p>
065         * This method is implicitly generic and return something which extends
066         * Node. The return type is the one of the left part of the assignment. For
067         * example, in the following call :
068         * 
069         * <pre>
070         * ExtendedNode n = edge.getNode0();
071         * </pre>
072         * 
073         * the method will return an ExtendedNode. If no left part exists, method
074         * will just return a Node.
075         * </p>
076         * 
077         * @see #getNode1()
078         * @see #getSourceNode()
079         * @return The first node of the edge.
080         */
081        <T extends Node> T getNode0();
082
083        /**
084         * Second node of the edge.
085         * <p>
086         * This is equivalent to the {@link #getTargetNode()} method, but may be
087         * clearer in the source code if the graph you are using is not directed.
088         * </p>
089         * <p>
090         * This method is implicitly generic and return something which extends
091         * Node. The return type is the one of the left part of the assignment. For
092         * example, in the following call :
093         * 
094         * <pre>
095         * ExtendedNode n = edge.getNode1();
096         * </pre>
097         * 
098         * the method will return an ExtendedNode. If no left part exists, method
099         * will just return a Node.
100         * </p>
101         * 
102         * @see #getNode0()
103         * @see #getTargetNode()
104         * @return The second node of the edge.
105         */
106        <T extends Node> T getNode1();
107
108        /**
109         * Start node.
110         * <p>
111         * When the edge is directed this is the source node, in this case you can
112         * get the opposite node using {@link #getTargetNode()}. This is equivalent
113         * to the {@link #getNode0()} method but may be clearer in the source code
114         * if the graph you are using is directed.
115         * </p>
116         * <p>
117         * This method is implicitly generic and return something which extends
118         * Node. The return type is the one of the left part of the assignment. For
119         * example, in the following call :
120         * 
121         * <pre>
122         * ExtendedNode n = edge.getSourceNode();
123         * </pre>
124         * 
125         * the method will return an ExtendedNode. If no left part exists, method
126         * will just return a Node.
127         * </p>
128         * 
129         * @see #getNode0()
130         * @see #getTargetNode()
131         * @return The origin node of the edge.
132         */
133        <T extends Node> T getSourceNode();
134
135        /**
136         * End node.
137         * <p>
138         * When the edge is directed this is the target node, in this case you can
139         * get the opposite node using {@link #getSourceNode()}. This is equivalent
140         * to the {@link #getNode1()} method but may be clearer in the source code
141         * if the graph you are using is directed.
142         * </p>
143         * <p>
144         * This method is implicitly generic and return something which extends
145         * Node. The return type is the one of the left part of the assignment. For
146         * example, in the following call :
147         * 
148         * <pre>
149         * ExtendedNode n = edge.getTargetNode();
150         * </pre>
151         * 
152         * the method will return an ExtendedNode. If no left part exists, method
153         * will just return a Node.
154         * </p>
155         * 
156         * @see #getNode1()
157         * @see #getSourceNode()
158         * @return The destination node of the edge.
159         */
160        <T extends Node> T getTargetNode();
161
162        /**
163         * When knowing one node and one edge of this node, this method return the
164         * node at the other end of the edge.
165         * <p>
166         * Return null if the given node is not at any end of the edge.
167         * </p>
168         * <p>
169         * This method is implicitly generic and return something which extends
170         * Node. The return type is the one of the left part of the assignment. For
171         * example, in the following call :
172         * 
173         * <pre>
174         * ExtendedNode n = edge.getOppositeNode((ExtendedNode) m);
175         * </pre>
176         * 
177         * the method will return an ExtendedNode. If no left part exists, method
178         * will just return a Node.
179         * </p>
180         * 
181         * @param node
182         *            The node we search the opposite of.
183         * @return the opposite node of the given node.
184         */
185        <T extends Node> T getOpposite(Node node);
186}