001: /*
002: * This file or a portion of this file is licensed under the terms of
003: * the Globus Toolkit Public License, found in file GTPL, or at
004: * http://www.globus.org/toolkit/download/license.html. This notice must
005: * appear in redistributions of this file, with or without modification.
006: *
007: * Redistributions of this Software, with or without modification, must
008: * reproduce the GTPL in: (1) the Software, or (2) the Documentation or
009: * some other similar material which is provided with the Software (if
010: * any).
011: *
012: * Copyright 1999-2004 University of Chicago and The University of
013: * Southern California. All rights reserved.
014: */
015:
016: package org.griphyn.common.catalog;
017:
018: import java.util.List;
019: import java.util.ArrayList;
020:
021: /**
022: * Class to notify of failures. Exceptions are chained like the
023: * {@link java.sql.SQLException} interface.<p>
024: *
025: * Here is a fragment of code to chain exceptions for later throwing:<p>
026: *
027: * <pre>
028: * CatalogException rce = null;
029: * ... some loop code ... {
030: * ...
031: * if ( exception triggered ) {
032: * if ( rce == null ) rce = new CatalogException( reason );
033: * else rce.setNextException( new CatalogException(reason) );
034: * ...
035: * } ... loop end ...
036: * if ( rce != null ) throw rce;
037: * </pre>
038: *
039: * Here is a fragment of code to unchain exceptions in the client:<p>
040: *
041: * <pre>
042: * try {
043: * ... operation ...
044: * } catch ( CatalogException rce ) {
045: * for ( ; rce != null; rce = rce.getNextException ) {
046: * ... do something with the payload ...
047: * }
048: * }
049: * </pre>
050: *
051: * @author Karan Vahi
052: * @author Jens-S. Vöckler
053: */
054: public class CatalogException
055: // method A: no need to change interface, obsfuscated use, though
056: extends java.lang.RuntimeException
057: // method B: needs API small change, but makes things clear.
058: // extends java.lang.Exception
059: {
060: /**
061: * chains the next exception into line.
062: */
063: private CatalogException m_next_exception = null;
064:
065: /*
066: * Constructs a <code>CatalogException</code> with no detail
067: * message.
068: */
069: public CatalogException() {
070: super ();
071: m_next_exception = null;
072: }
073:
074: /**
075: * Constructs a <code>CatalogException</code> with the
076: * specified detailed message.
077: *
078: * @param s is the detailled message.
079: */
080: public CatalogException(String s) {
081: super (s);
082: m_next_exception = null;
083: }
084:
085: /**
086: * Constructs a <code>CatalogException</code> with the
087: * specified detailed message and a cause.
088: *
089: * @param s is the detailled message.
090: * @param cause is the cause (which is saved for later retrieval by the
091: * {@link java.lang.Throwable#getCause()} method). A <code>null</code>
092: * value is permitted, and indicates that the cause is nonexistent or
093: * unknown.
094: */
095: public CatalogException(String s, Throwable cause) {
096: super (s, cause);
097: m_next_exception = null;
098: }
099:
100: /**
101: * Constructs a <code>CatalogException</code> with the
102: * specified just a cause.
103: *
104: * @param cause is the cause (which is saved for later retrieval by the
105: * {@link java.lang.Throwable#getCause()} method). A <code>null</code>
106: * value is permitted, and indicates that the cause is nonexistent or
107: * unknown.
108: */
109: public CatalogException(Throwable cause) {
110: super (cause);
111: m_next_exception = null;
112: }
113:
114: /**
115: * Retrieves the exception chained to this
116: * <code>CatalogException</code> object.
117: *
118: * @return the next <code>CatalogException</code> object in the chain;
119: * <code>null</code> if there are none.
120: * @see #setNextException( CatalogException )
121: */
122: public CatalogException getNextException() {
123: return m_next_exception;
124: }
125:
126: /**
127: * Adds an <code>CatalogException<code> object to the end of
128: * the chain.
129: *
130: * @param ex the new exception that will be added to the end of the
131: * <code>CatalogException</code> chain.
132: * @see #getNextException()
133: */
134: public void setNextException(CatalogException ex) {
135: if (m_next_exception == null) {
136: m_next_exception = ex;
137: } else {
138: CatalogException temp, rce = m_next_exception;
139: while ((temp = rce.getNextException()) != null) {
140: rce = temp;
141: }
142: rce.setNextException(ex);
143: }
144: }
145: }
|