libjava/classpath/javax/security/sasl/SaslException.java

   1 /* SaslException.java
   2    Copyright (C) 2003, 2005, Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.security.sasl;
  40
  41 import gnu.java.lang.CPStringBuilder;
  42
  43 import java.io.IOException;
  44 import java.io.PrintStream;
  45 import java.io.PrintWriter;
  46 import java.io.Serializable;
  47
  48 /**
  49  * This class represents an error that has occurred when using SASL.
  50  *
  51  * @since 1.5
  52  */
  53 public class SaslException extends IOException implements Serializable
  54 {
  55
  56   // Constants and variables
  57   // -------------------------------------------------------------------------
  58
  59   private static final long serialVersionUID = 4579784287983423626L;
  60
  61   /**
  62    * @serial The possibly null root cause exception.
  63    */
  64   private Throwable _exception = null;
  65
  66   // Constructor(s)
  67   // -------------------------------------------------------------------------
  68
  69   /**
  70    * Constructs a new instance of <code>SaslException</code>. The root
  71    * exception and the detailed message are null.
  72    */
  73   public SaslException()
  74   {
  75     super();
  76   }
  77
  78   /**
  79    * Constructs a new instance of <code>SaslException</code> with a detailed
  80    * message. The <code>root</code> exception is <code>null</code>.
  81    *
  82    * @param detail a possibly null string containing details of the exception.
  83    * @see Throwable#getMessage()
  84    */
  85   public SaslException(String detail)
  86   {
  87     super(detail);
  88   }
  89
  90   /**
  91    * Constructs a new instance of <code>SaslException</code> with a detailed
  92    * message and a root exception. For example, a <code>SaslException</code>
  93    * might result from a problem with the callback handler, which might throw a
  94    * {@link javax.security.auth.callback.UnsupportedCallbackException} if it
  95    * does not support the requested callback, or throw an {@link IOException}
  96    * if it had problems obtaining data for the callback. The
  97    * <code>SaslException</code>'s root exception would be then be the exception
  98    * thrown by the callback handler.
  99    *
 100    * @param detail a possibly <code>null</code> string containing details of
 101    * the exception.
 102    * @param ex a possibly <code>null</code> root exception that caused this
 103    * exception.
 104    * @see Throwable#getMessage()
 105    * @see #getCause()
 106    */
 107   public SaslException(String detail, Throwable ex)
 108   {
 109     super(detail);
 110     _exception = ex;
 111   }
 112
 113   // Class methods
 114   // -------------------------------------------------------------------------
 115
 116   // Instance methods
 117   // -------------------------------------------------------------------------
 118
 119   /**
 120    * Returns the cause of this throwable or <code>null</code> if the cause is
 121    * nonexistent or unknown. The cause is the throwable that caused this
 122    * exception to be thrown.
 123    *
 124    * @return the possibly <code>null</code> exception that caused this exception.
 125    */
 126   public Throwable getCause()
 127   {
 128     return _exception;
 129   }
 130
 131   /**
 132    * Prints this exception's stack trace to <code>System.err</code>. If this
 133    * exception has a root exception; the stack trace of the root exception is
 134    * also printed to <code>System.err</code>.
 135    */
 136   public void printStackTrace()
 137   {
 138     super.printStackTrace();
 139     if (_exception != null)
 140       _exception.printStackTrace();
 141   }
 142
 143   /**
 144    * Prints this exception's stack trace to a print stream. If this exception
 145    * has a root exception; the stack trace of the root exception is also
 146    * printed to the print stream.
 147    *
 148    * @param ps the non-null print stream to which to print.
 149    */
 150   public void printStackTrace(PrintStream ps)
 151   {
 152     super.printStackTrace(ps);
 153     if (_exception != null)
 154       _exception.printStackTrace(ps);
 155   }
 156
 157   /**
 158    * Prints this exception's stack trace to a print writer. If this exception
 159    * has a root exception; the stack trace of the root exception is also
 160    * printed to the print writer.
 161    *
 162    * @param pw the non-null print writer to use for output.
 163    */
 164   public void printStackTrace(PrintWriter pw)
 165   {
 166     super.printStackTrace(pw);
 167     if (_exception != null)
 168       _exception.printStackTrace(pw);
 169   }
 170
 171   /**
 172    * Returns the string representation of this exception. The string
 173    * representation contains this exception's class name, its detailed
 174    * messsage, and if it has a root exception, the string representation of the
 175    * root exception. This string representation is meant for debugging and not
 176    * meant to be interpreted programmatically.
 177    *
 178    * @return the non-null string representation of this exception.
 179    * @see Throwable#getMessage()
 180    */
 181   public String toString()
 182   {
 183     CPStringBuilder sb = new CPStringBuilder(this.getClass().getName())
 184       .append(": ").append(super.toString());
 185     if (_exception != null)
 186       sb.append("; caused by: ").append(_exception.toString());
 187     return sb.toString();
 188   }
 189 }