001/* Base exception for graph errors.
002
003 Copyright (c) 2002-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 */
025package ptolemy.graph;
026
027///////////////////////////////////////////////////////////////////
028//// GraphException
029
030/**
031 Base exception for graph errors. This is also an instance of
032 <code>RuntimeException</code>.
033
034 @author Mingyung Ko, Shuvra S. Bhattacharyya
035 @version $Id$
036 @since Ptolemy II 2.1
037 @Pt.ProposedRating Red (myko)
038 @Pt.AcceptedRating Red (ssb)
039 */
040@SuppressWarnings("serial")
041public class GraphException extends RuntimeException {
042    /** The default constructor without arguments.
043     */
044    public GraphException() {
045        // Note: this nullary exception is required.  If it is
046        // not present, then the subclasses of this class will not
047        // compile.
048        this(null);
049    }
050
051    /** Constructor with an argument of text description.
052     *  @param message The exception message.
053     */
054    public GraphException(String message) {
055        super(message);
056    }
057
058    ///////////////////////////////////////////////////////////////////
059    ////                         public methods                    ////
060
061    /** Return a dump of this graph suitable to be appended to an
062     *  error message.
063     *
064     *  @param graph The graph to dump.
065     *  @return A text string dump of the graph.
066     */
067    static public String graphDump(Graph graph) {
068        return "\nA Dump of the offending graph follows.\n" + graph.toString()
069                + "\n";
070    }
071
072    /** Return a dump of a graph element and the container graph suitable to
073     *  be appended to an error message.
074     *
075     *  @param element The element to dump.
076     *  @param graph The graph where the element resides.
077     *  @return A text string dump of the element and graph.
078     */
079    static public String elementDump(Element element, Graph graph) {
080        String descriptor;
081
082        if (element == null) {
083            descriptor = "element";
084        } else {
085            descriptor = element.descriptor();
086        }
087
088        return _elementDump(element, graph, descriptor);
089    }
090
091    /** Return a dump of a weight and the container graph suitable to
092     *  be appended to an error message. Generally, an
093     *  {@link #elementDump(Element, Graph)} follows.
094     *
095     *  @param weight The weight to dump.
096     *  @return A text string dump of the weight and graph.
097     */
098    static public String weightDump(Object weight) {
099        if (weight == null) {
100            return "\nThe weight was null?";
101        }
102        String dump = "\nThe weight is of class " + weight.getClass().getName()
103                + " and its description follows:\n" + weight.toString();
104        return dump;
105    }
106
107    ///////////////////////////////////////////////////////////////////
108    ////                         protected methods                 ////
109
110    /** Return a dump of an element ({@link Node}, {@link Edge},
111     *  or weight) and the container graph suitable to be appended
112     *  to an error message.
113     *
114     *  @param element The element to dump.
115     *  @param graph The container graph.
116     *  @param elementDescriptor Descriptor of the element.
117     *  @return A text string dump of the element and graph.
118     */
119    static protected String _elementDump(Object element, Graph graph,
120            String elementDescriptor) {
121        String elementString = element == null ? "<null>" : element.toString();
122        return "\nDumps of the offending " + elementDescriptor
123                + " and graph follow.\n" + "The offending " + elementDescriptor
124                + ":\n" + elementString + "\nThe offending graph:\n"
125                + graph.toString() + "\n";
126    }
127}