1   /*
    2    * Copyright (c) 1999, 2003, Oracle and/or its affiliates. All rights reserved.
    3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
    4    *
    5    * This code is free software; you can redistribute it and/or modify it
    6    * under the terms of the GNU General Public License version 2 only, as
    7    * published by the Free Software Foundation.  Oracle designates this
    8    * particular file as subject to the "Classpath" exception as provided
    9    * by Oracle in the LICENSE file that accompanied this code.
   10    *
   11    * This code is distributed in the hope that it will be useful, but WITHOUT
   12    * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
   13    * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
   14    * version 2 for more details (a copy is included in the LICENSE file that
   15    * accompanied this code).
   16    *
   17    * You should have received a copy of the GNU General Public License version
   18    * 2 along with this work; if not, write to the Free Software Foundation,
   19    * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   20    *
   21    * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
   22    * or visit www.oracle.com if you need additional information or have any
   23    * questions.
   24    */
   25   
   26   package javax.security.sasl;
   27   
   28   import java.io.IOException;
   29   
   30   /**
   31    * This class represents an error that has occurred when using SASL.
   32    *
   33    * @since 1.5
   34    *
   35    * @author Rosanna Lee
   36    * @author Rob Weltman
   37    */
   38   
   39   public class SaslException extends IOException {
   40       /**
   41        * The possibly null root cause exception.
   42        * @serial
   43        */
   44       // Required for serialization interoperability with JSR 28
   45       private Throwable _exception;
   46   
   47       /**
   48        * Constructs a new instance of <tt>SaslException</tt>.
   49        * The root exception and the detailed message are null.
   50        */
   51       public SaslException () {
   52           super();
   53       }
   54   
   55       /**
   56        * Constructs a new instance of <tt>SaslException</tt> with a detailed message.
   57        * The root exception is null.
   58        * @param detail A possibly null string containing details of the exception.
   59        *
   60        * @see java.lang.Throwable#getMessage
   61        */
   62       public SaslException (String detail) {
   63           super(detail);
   64       }
   65   
   66       /**
   67        * Constructs a new instance of <tt>SaslException</tt> with a detailed message
   68        * and a root exception.
   69        * For example, a SaslException might result from a problem with
   70        * the callback handler, which might throw a NoSuchCallbackException if
   71        * it does not support the requested callback, or throw an IOException
   72        * if it had problems obtaining data for the callback. The
   73        * SaslException's root exception would be then be the exception thrown
   74        * by the callback handler.
   75        *
   76        * @param detail A possibly null string containing details of the exception.
   77        * @param ex A possibly null root exception that caused this exception.
   78        *
   79        * @see java.lang.Throwable#getMessage
   80        * @see #getCause
   81        */
   82       public SaslException (String detail, Throwable ex) {
   83           super(detail);
   84           if (ex != null) {
   85               initCause(ex);
   86           }
   87       }
   88   
   89       /*
   90        * Override Throwable.getCause() to ensure deserialized object from
   91        * JSR 28 would return same value for getCause() (i.e., _exception).
   92        */
   93       public Throwable getCause() {
   94           return _exception;
   95       }
   96   
   97       /*
   98        * Override Throwable.initCause() to match getCause() by updating
   99        * _exception as well.
  100        */
  101       public Throwable initCause(Throwable cause) {
  102           super.initCause(cause);
  103           _exception = cause;
  104           return this;
  105       }
  106   
  107       /**
  108        * Returns the string representation of this exception.
  109        * The string representation contains
  110        * this exception's class name, its detailed messsage, and if
  111        * it has a root exception, the string representation of the root
  112        * exception. This string representation
  113        * is meant for debugging and not meant to be interpreted
  114        * programmatically.
  115        * @return The non-null string representation of this exception.
  116        * @see java.lang.Throwable#getMessage
  117        */
  118       // Override Throwable.toString() to conform to JSR 28
  119       public String toString() {
  120           String answer = super.toString();
  121           if (_exception != null && _exception != this) {
  122               answer += " [Caused by " + _exception.toString() + "]";
  123           }
  124           return answer;
  125       }
  126   
  127       /** Use serialVersionUID from JSR 28 RI for interoperability */
  128       private static final long serialVersionUID = 4579784287983423626L;
  129   }