001/* A weighted or unweighted edge for a directed or undirected graph.
002
003 Copyright (c) 2001-2014 The University of Maryland
004 All rights reserved.
005 Permission is hereby granted, without written agreement and without
006 license or royalty fees, to use, copy, modify, and distribute this
007 software and its documentation for any purpose, provided that the above
008 copyright notice and the following two paragraphs appear in all copies
009 of this software.
010
011 IN NO EVENT SHALL THE UNIVERSITY OF MARYLAND BE LIABLE TO ANY PARTY
012 FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
013 ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
014 THE UNIVERSITY OF MARYLAND HAS BEEN ADVISED OF THE POSSIBILITY OF
015 SUCH DAMAGE.
016
017 THE UNIVERSITY OF MARYLAND SPECIFICALLY DISCLAIMS ANY WARRANTIES,
018 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
019 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
020 PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
021 MARYLAND HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
022 ENHANCEMENTS, OR MODIFICATIONS.
023
024
025 */
026package ptolemy.graph;
027
028////////////////////////////////////////////////////////////////////////// //
029//Edge
030
031/**
032 A weighted or unweighted edge for a directed or undirected graph.  The
033 connectivity of edges is specified by <i>source</i> nodes and <i>sink</i>
034 nodes. A directed edge is directed <i>from</i> its source node <i>to</i> its
035 sink node. For an undirected edge, the source node is simply the first node
036 that was specified when the edge was created, and the sink node is the
037 second node.  This convention allows undirected edges to later be converted
038 in a consistent manner to directed edges, if desired.
039
040 <p>On creation of an edge, an arbitrary object can be associated with the
041 edge as the weight of the edge.  We say that an edge is <i>unweighted</i> if
042 it does not have an assigned weight. It is an error to attempt to access the
043 weight of an unweighted edge.
044
045 <p>Self-loop edges (edges whose source and sink nodes are identical)
046 are allowed.
047
048 <p> Once an edge is created, its source node and sink node cannot be changed.
049
050 @author Shuvra S. Bhattacharyya
051 @version $Id$
052 @since Ptolemy II 2.0
053 @Pt.ProposedRating Red (cxh)
054 @Pt.AcceptedRating Red (cxh)
055 @see ptolemy.graph.Node
056 */
057public final class Edge extends Element {
058    /** Construct an unweighted edge with a specified source node and sink node.
059     *  @param source The source node.
060     *  @param sink The sink node.
061     */
062    public Edge(Node source, Node sink) {
063        super();
064        _source = source;
065        _sink = sink;
066    }
067
068    /** Construct a weighted edge with a specified source node, sink node, and
069     *  edge weight.
070     *  @param source The source node.
071     *  @param sink The sink node.
072     *  @param weight The edge weight.
073     *  @exception IllegalArgumentException If the specified weight is
074     *  <code>null</code>.
075     */
076    public Edge(Node source, Node sink, Object weight) {
077        this(source, sink);
078        setWeight(weight);
079    }
080
081    ///////////////////////////////////////////////////////////////////
082    ////                         public methods                    ////
083
084    /** A one-word description of the type of this graph element.
085     *  @return The description.
086     */
087    @Override
088    public String descriptor() {
089        return "edge";
090    }
091
092    /** Return true if this is a self-loop edge.
093     *  @return True if this is a self-loop edge.
094     */
095    public boolean isSelfLoop() {
096        return _source == _sink;
097    }
098
099    /** Return the sink node of the edge.
100     *  @return The sink node.
101     */
102    public Node sink() {
103        return _sink;
104    }
105
106    /** Return the source node of the edge.
107     *  @return The source node.
108     */
109    public Node source() {
110        return _source;
111    }
112
113    /** Return a string representation of the edge, optionally including
114     *  information about the edge weight. The string
115     *  representation is of the form
116     *
117     *  <p> <code>(source, sink, weight)</code>,
118     *
119     *  <p> where <code>source</code>, <code>sink</code>, and
120     *  <code>weight</code>
121     *
122     *  are string representations
123     *  of the source node, sink node, and edge weight, respectively.
124     *  If the edge is unweighted or the <code>showWeight</code> argument is
125     *  false, then the string representation is simply
126     *
127     *  <p> <code>(source, sink)</code>.
128     *
129     *  @param showWeight True to include a string representation of the edge
130     *  weight in the string representation of the edge.
131     *  @return A string representation of the edge.
132     */
133    public String toString(boolean showWeight) {
134        String result = "(" + _source + ", " + _sink;
135
136        if (showWeight && hasWeight()) {
137            result += ", " + _weight;
138        }
139
140        result += ")";
141        return result;
142    }
143
144    /** Return a string representation of the edge, including information
145     *  about the edge weight.
146     *  @return A string representation of the edge.
147     *  @see #toString(boolean)
148     */
149    @Override
150    public String toString() {
151        return toString(true);
152    }
153
154    ///////////////////////////////////////////////////////////////////
155    ////                         private variables                 ////
156    // The sink node of the edge.
157    private Node _sink;
158
159    // The source node of the edge.
160    private Node _source;
161}