001    /* SaslException.java
002       Copyright (C) 2003, 2005, Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.security.sasl;
040    
041    import java.io.IOException;
042    import java.io.PrintStream;
043    import java.io.PrintWriter;
044    import java.io.Serializable;
045    
046    /**
047     * This class represents an error that has occurred when using SASL.
048     *
049     * @since 1.5
050     */
051    public class SaslException extends IOException implements Serializable
052    {
053    
054      // Constants and variables
055      // -------------------------------------------------------------------------
056    
057      private static final long serialVersionUID = 4579784287983423626L;
058    
059      /**
060       * @serial The possibly null root cause exception.
061       */
062      private Throwable _exception = null;
063    
064      // Constructor(s)
065      // -------------------------------------------------------------------------
066    
067      /**
068       * Constructs a new instance of <code>SaslException</code>. The root
069       * exception and the detailed message are null.
070       */
071      public SaslException()
072      {
073        super();
074      }
075    
076      /**
077       * Constructs a new instance of <code>SaslException</code> with a detailed
078       * message. The <code>root</code> exception is <code>null</code>.
079       *
080       * @param detail a possibly null string containing details of the exception.
081       * @see Throwable#getMessage()
082       */
083      public SaslException(String detail)
084      {
085        super(detail);
086      }
087    
088      /**
089       * Constructs a new instance of <code>SaslException</code> with a detailed
090       * message and a root exception. For example, a <code>SaslException</code>
091       * might result from a problem with the callback handler, which might throw a
092       * {@link javax.security.auth.callback.UnsupportedCallbackException} if it
093       * does not support the requested callback, or throw an {@link IOException}
094       * if it had problems obtaining data for the callback. The
095       * <code>SaslException</code>'s root exception would be then be the exception
096       * thrown by the callback handler.
097       *
098       * @param detail a possibly <code>null</code> string containing details of
099       * the exception.
100       * @param ex a possibly <code>null</code> root exception that caused this
101       * exception.
102       * @see Throwable#getMessage()
103       * @see #getCause()
104       */
105      public SaslException(String detail, Throwable ex)
106      {
107        super(detail);
108        _exception = ex;
109      }
110    
111      // Class methods
112      // -------------------------------------------------------------------------
113    
114      // Instance methods
115      // -------------------------------------------------------------------------
116    
117      /**
118       * Returns the cause of this throwable or <code>null</code> if the cause is
119       * nonexistent or unknown. The cause is the throwable that caused this
120       * exception to be thrown.
121       *
122       * @return the possibly <code>null</code> exception that caused this exception.
123       */
124      public Throwable getCause()
125      {
126        return _exception;
127      }
128    
129      /**
130       * Prints this exception's stack trace to <code>System.err</code>. If this
131       * exception has a root exception; the stack trace of the root exception is
132       * also printed to <code>System.err</code>.
133       */
134      public void printStackTrace()
135      {
136        super.printStackTrace();
137        if (_exception != null)
138          _exception.printStackTrace();
139      }
140    
141      /**
142       * Prints this exception's stack trace to a print stream. If this exception
143       * has a root exception; the stack trace of the root exception is also
144       * printed to the print stream.
145       *
146       * @param ps the non-null print stream to which to print.
147       */
148      public void printStackTrace(PrintStream ps)
149      {
150        super.printStackTrace(ps);
151        if (_exception != null)
152          _exception.printStackTrace(ps);
153      }
154    
155      /**
156       * Prints this exception's stack trace to a print writer. If this exception
157       * has a root exception; the stack trace of the root exception is also
158       * printed to the print writer.
159       *
160       * @param pw the non-null print writer to use for output.
161       */
162      public void printStackTrace(PrintWriter pw)
163      {
164        super.printStackTrace(pw);
165        if (_exception != null)
166          _exception.printStackTrace(pw);
167      }
168    
169      /**
170       * Returns the string representation of this exception. The string
171       * representation contains this exception's class name, its detailed
172       * messsage, and if it has a root exception, the string representation of the
173       * root exception. This string representation is meant for debugging and not
174       * meant to be interpreted programmatically.
175       *
176       * @return the non-null string representation of this exception.
177       * @see Throwable#getMessage()
178       */
179      public String toString()
180      {
181        StringBuffer sb = new StringBuffer(this.getClass().getName())
182          .append(": ").append(super.toString());
183        if (_exception != null)
184          sb.append("; caused by: ").append(_exception.toString());
185        return sb.toString();
186      }
187    }