src/share/classes/java/security/cert/CertPathValidatorException.java

Print this page




  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 java.security.cert;
  27 
  28 import java.io.InvalidObjectException;
  29 import java.io.IOException;
  30 import java.io.ObjectInputStream;
  31 import java.security.GeneralSecurityException;
  32 
  33 /**
  34  * An exception indicating one of a variety of problems encountered when
  35  * validating a certification path.
  36  * <p>
  37  * A <code>CertPathValidatorException</code> provides support for wrapping
  38  * exceptions. The {@link #getCause getCause} method returns the throwable,
  39  * if any, that caused this exception to be thrown.
  40  * <p>
  41  * A <code>CertPathValidatorException</code> may also include the
  42  * certification path that was being validated when the exception was thrown,
  43  * the index of the certificate in the certification path that caused the
  44  * exception to be thrown, and the reason that caused the failure. Use the
  45  * {@link #getCertPath getCertPath}, {@link #getIndex getIndex}, and
  46  * {@link #getReason getReason} methods to retrieve this information.
  47  *
  48  * <p>
  49  * <b>Concurrent Access</b>
  50  * <p>
  51  * Unless otherwise specified, the methods defined in this class are not
  52  * thread-safe. Multiple threads that need to access a single
  53  * object concurrently should synchronize amongst themselves and
  54  * provide the necessary locking. Multiple threads each manipulating
  55  * separate objects need not synchronize.
  56  *
  57  * @see CertPathValidator
  58  *
  59  * @since       1.4
  60  * @author      Yassir Elley
  61  */
  62 public class CertPathValidatorException extends GeneralSecurityException {
  63 
  64     private static final long serialVersionUID = -3083180014971893139L;
  65 
  66     /**
  67      * @serial the index of the certificate in the certification path
  68      * that caused the exception to be thrown
  69      */
  70     private int index = -1;
  71 
  72     /**
  73      * @serial the <code>CertPath</code> that was being validated when
  74      * the exception was thrown
  75      */
  76     private CertPath certPath;
  77 
  78     /**
  79      * @serial the reason the validation failed
  80      */
  81     private Reason reason = BasicReason.UNSPECIFIED;
  82 
  83     /**
  84      * Creates a <code>CertPathValidatorException</code> with
  85      * no detail message.
  86      */
  87     public CertPathValidatorException() {
  88         this(null, null);
  89     }
  90 
  91     /**
  92      * Creates a <code>CertPathValidatorException</code> with the given
  93      * detail message. A detail message is a <code>String</code> that
  94      * describes this particular exception.
  95      *
  96      * @param msg the detail message
  97      */
  98     public CertPathValidatorException(String msg) {
  99         this(msg, null);
 100     }
 101 
 102     /**
 103      * Creates a <code>CertPathValidatorException</code> that wraps the
 104      * specified throwable. This allows any exception to be converted into a
 105      * <code>CertPathValidatorException</code>, while retaining information
 106      * about the wrapped exception, which may be useful for debugging. The
 107      * detail message is set to (<code>cause==null ? null : cause.toString()
 108      * </code>) (which typically contains the class and detail message of
 109      * cause).
 110      *
 111      * @param cause the cause (which is saved for later retrieval by the
 112      * {@link #getCause getCause()} method). (A <code>null</code> value is
 113      * permitted, and indicates that the cause is nonexistent or unknown.)
 114      */
 115     public CertPathValidatorException(Throwable cause) {
 116         this((cause == null ? null : cause.toString()), cause);
 117     }
 118 
 119     /**
 120      * Creates a <code>CertPathValidatorException</code> with the specified
 121      * detail message and cause.
 122      *
 123      * @param msg the detail message
 124      * @param cause the cause (which is saved for later retrieval by the
 125      * {@link #getCause getCause()} method). (A <code>null</code> value is
 126      * permitted, and indicates that the cause is nonexistent or unknown.)
 127      */
 128     public CertPathValidatorException(String msg, Throwable cause) {
 129         this(msg, cause, null, -1);
 130     }
 131 
 132     /**
 133      * Creates a <code>CertPathValidatorException</code> with the specified
 134      * detail message, cause, certification path, and index.
 135      *
 136      * @param msg the detail message (or <code>null</code> if none)
 137      * @param cause the cause (or <code>null</code> if none)
 138      * @param certPath the certification path that was in the process of
 139      * being validated when the error was encountered
 140      * @param index the index of the certificate in the certification path
 141      * that caused the error (or -1 if not applicable). Note that
 142      * the list of certificates in a <code>CertPath</code> is zero based.
 143      * @throws IndexOutOfBoundsException if the index is out of range
 144      * {@code (index < -1 || (certPath != null && index >=
 145      * certPath.getCertificates().size()) }
 146      * @throws IllegalArgumentException if <code>certPath</code> is
 147      * <code>null</code> and <code>index</code> is not -1
 148      */
 149     public CertPathValidatorException(String msg, Throwable cause,
 150             CertPath certPath, int index) {
 151         this(msg, cause, certPath, index, BasicReason.UNSPECIFIED);
 152     }
 153 
 154     /**
 155      * Creates a <code>CertPathValidatorException</code> with the specified
 156      * detail message, cause, certification path, index, and reason.
 157      *
 158      * @param msg the detail message (or <code>null</code> if none)
 159      * @param cause the cause (or <code>null</code> if none)
 160      * @param certPath the certification path that was in the process of
 161      * being validated when the error was encountered
 162      * @param index the index of the certificate in the certification path
 163      * that caused the error (or -1 if not applicable). Note that
 164      * the list of certificates in a <code>CertPath</code> is zero based.
 165      * @param reason the reason the validation failed
 166      * @throws IndexOutOfBoundsException if the index is out of range
 167      * {@code (index < -1 || (certPath != null && index >=
 168      * certPath.getCertificates().size()) }
 169      * @throws IllegalArgumentException if <code>certPath</code> is
 170      * <code>null</code> and <code>index</code> is not -1
 171      * @throws NullPointerException if <code>reason</code> is <code>null</code>
 172      *
 173      * @since 1.7
 174      */
 175     public CertPathValidatorException(String msg, Throwable cause,
 176             CertPath certPath, int index, Reason reason) {
 177         super(msg, cause);
 178         if (certPath == null && index != -1) {
 179             throw new IllegalArgumentException();
 180         }
 181         if (index < -1 ||
 182             (certPath != null && index >= certPath.getCertificates().size())) {
 183             throw new IndexOutOfBoundsException();
 184         }
 185         if (reason == null) {
 186             throw new NullPointerException("reason can't be null");
 187         }
 188         this.certPath = certPath;
 189         this.index = index;
 190         this.reason = reason;
 191     }
 192 
 193     /**
 194      * Returns the certification path that was being validated when
 195      * the exception was thrown.
 196      *
 197      * @return the <code>CertPath</code> that was being validated when
 198      * the exception was thrown (or <code>null</code> if not specified)
 199      */
 200     public CertPath getCertPath() {
 201         return this.certPath;
 202     }
 203 
 204     /**
 205      * Returns the index of the certificate in the certification path
 206      * that caused the exception to be thrown. Note that the list of
 207      * certificates in a <code>CertPath</code> is zero based. If no
 208      * index has been set, -1 is returned.
 209      *
 210      * @return the index that has been set, or -1 if none has been set
 211      */
 212     public int getIndex() {
 213         return this.index;
 214     }
 215 
 216     /**
 217      * Returns the reason that the validation failed. The reason is
 218      * associated with the index of the certificate returned by
 219      * {@link #getIndex}.
 220      *
 221      * @return the reason that the validation failed, or
 222      *    <code>BasicReason.UNSPECIFIED</code> if a reason has not been
 223      *    specified
 224      *
 225      * @since 1.7
 226      */
 227     public Reason getReason() {
 228         return this.reason;
 229     }
 230 
 231     private void readObject(ObjectInputStream stream)
 232         throws ClassNotFoundException, IOException {
 233         stream.defaultReadObject();
 234         if (reason == null) {
 235             reason = BasicReason.UNSPECIFIED;
 236         }
 237         if (certPath == null && index != -1) {
 238             throw new InvalidObjectException("certpath is null and index != -1");
 239         }
 240         if (index < -1 ||
 241             (certPath != null && index >= certPath.getCertificates().size())) {
 242             throw new InvalidObjectException("index out of range");




  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 java.security.cert;
  27 
  28 import java.io.InvalidObjectException;
  29 import java.io.IOException;
  30 import java.io.ObjectInputStream;
  31 import java.security.GeneralSecurityException;
  32 
  33 /**
  34  * An exception indicating one of a variety of problems encountered when
  35  * validating a certification path.
  36  * <p>
  37  * A {@code CertPathValidatorException} provides support for wrapping
  38  * exceptions. The {@link #getCause getCause} method returns the throwable,
  39  * if any, that caused this exception to be thrown.
  40  * <p>
  41  * A {@code CertPathValidatorException} may also include the
  42  * certification path that was being validated when the exception was thrown,
  43  * the index of the certificate in the certification path that caused the
  44  * exception to be thrown, and the reason that caused the failure. Use the
  45  * {@link #getCertPath getCertPath}, {@link #getIndex getIndex}, and
  46  * {@link #getReason getReason} methods to retrieve this information.
  47  *
  48  * <p>
  49  * <b>Concurrent Access</b>
  50  * <p>
  51  * Unless otherwise specified, the methods defined in this class are not
  52  * thread-safe. Multiple threads that need to access a single
  53  * object concurrently should synchronize amongst themselves and
  54  * provide the necessary locking. Multiple threads each manipulating
  55  * separate objects need not synchronize.
  56  *
  57  * @see CertPathValidator
  58  *
  59  * @since       1.4
  60  * @author      Yassir Elley
  61  */
  62 public class CertPathValidatorException extends GeneralSecurityException {
  63 
  64     private static final long serialVersionUID = -3083180014971893139L;
  65 
  66     /**
  67      * @serial the index of the certificate in the certification path
  68      * that caused the exception to be thrown
  69      */
  70     private int index = -1;
  71 
  72     /**
  73      * @serial the {@code CertPath} that was being validated when
  74      * the exception was thrown
  75      */
  76     private CertPath certPath;
  77 
  78     /**
  79      * @serial the reason the validation failed
  80      */
  81     private Reason reason = BasicReason.UNSPECIFIED;
  82 
  83     /**
  84      * Creates a {@code CertPathValidatorException} with
  85      * no detail message.
  86      */
  87     public CertPathValidatorException() {
  88         this(null, null);
  89     }
  90 
  91     /**
  92      * Creates a {@code CertPathValidatorException} with the given
  93      * detail message. A detail message is a {@code String} that
  94      * describes this particular exception.
  95      *
  96      * @param msg the detail message
  97      */
  98     public CertPathValidatorException(String msg) {
  99         this(msg, null);
 100     }
 101 
 102     /**
 103      * Creates a {@code CertPathValidatorException} that wraps the
 104      * specified throwable. This allows any exception to be converted into a
 105      * {@code CertPathValidatorException}, while retaining information
 106      * about the wrapped exception, which may be useful for debugging. The
 107      * detail message is set to ({@code cause==null ? null : cause.toString()})
 108      * (which typically contains the class and detail message of
 109      * cause).
 110      *
 111      * @param cause the cause (which is saved for later retrieval by the
 112      * {@link #getCause getCause()} method). (A {@code null} value is
 113      * permitted, and indicates that the cause is nonexistent or unknown.)
 114      */
 115     public CertPathValidatorException(Throwable cause) {
 116         this((cause == null ? null : cause.toString()), cause);
 117     }
 118 
 119     /**
 120      * Creates a {@code CertPathValidatorException} with the specified
 121      * detail message and cause.
 122      *
 123      * @param msg the detail message
 124      * @param cause the cause (which is saved for later retrieval by the
 125      * {@link #getCause getCause()} method). (A {@code null} value is
 126      * permitted, and indicates that the cause is nonexistent or unknown.)
 127      */
 128     public CertPathValidatorException(String msg, Throwable cause) {
 129         this(msg, cause, null, -1);
 130     }
 131 
 132     /**
 133      * Creates a {@code CertPathValidatorException} with the specified
 134      * detail message, cause, certification path, and index.
 135      *
 136      * @param msg the detail message (or {@code null} if none)
 137      * @param cause the cause (or {@code null} if none)
 138      * @param certPath the certification path that was in the process of
 139      * being validated when the error was encountered
 140      * @param index the index of the certificate in the certification path
 141      * that caused the error (or -1 if not applicable). Note that
 142      * the list of certificates in a {@code CertPath} is zero based.
 143      * @throws IndexOutOfBoundsException if the index is out of range
 144      * {@code (index < -1 || (certPath != null && index >=
 145      * certPath.getCertificates().size()) }
 146      * @throws IllegalArgumentException if {@code certPath} is
 147      * {@code null} and {@code index} is not -1
 148      */
 149     public CertPathValidatorException(String msg, Throwable cause,
 150             CertPath certPath, int index) {
 151         this(msg, cause, certPath, index, BasicReason.UNSPECIFIED);
 152     }
 153 
 154     /**
 155      * Creates a {@code CertPathValidatorException} with the specified
 156      * detail message, cause, certification path, index, and reason.
 157      *
 158      * @param msg the detail message (or {@code null} if none)
 159      * @param cause the cause (or {@code null} if none)
 160      * @param certPath the certification path that was in the process of
 161      * being validated when the error was encountered
 162      * @param index the index of the certificate in the certification path
 163      * that caused the error (or -1 if not applicable). Note that
 164      * the list of certificates in a {@code CertPath} is zero based.
 165      * @param reason the reason the validation failed
 166      * @throws IndexOutOfBoundsException if the index is out of range
 167      * {@code (index < -1 || (certPath != null && index >=
 168      * certPath.getCertificates().size()) }
 169      * @throws IllegalArgumentException if {@code certPath} is
 170      * {@code null} and {@code index} is not -1
 171      * @throws NullPointerException if {@code reason} is {@code null}
 172      *
 173      * @since 1.7
 174      */
 175     public CertPathValidatorException(String msg, Throwable cause,
 176             CertPath certPath, int index, Reason reason) {
 177         super(msg, cause);
 178         if (certPath == null && index != -1) {
 179             throw new IllegalArgumentException();
 180         }
 181         if (index < -1 ||
 182             (certPath != null && index >= certPath.getCertificates().size())) {
 183             throw new IndexOutOfBoundsException();
 184         }
 185         if (reason == null) {
 186             throw new NullPointerException("reason can't be null");
 187         }
 188         this.certPath = certPath;
 189         this.index = index;
 190         this.reason = reason;
 191     }
 192 
 193     /**
 194      * Returns the certification path that was being validated when
 195      * the exception was thrown.
 196      *
 197      * @return the {@code CertPath} that was being validated when
 198      * the exception was thrown (or {@code null} if not specified)
 199      */
 200     public CertPath getCertPath() {
 201         return this.certPath;
 202     }
 203 
 204     /**
 205      * Returns the index of the certificate in the certification path
 206      * that caused the exception to be thrown. Note that the list of
 207      * certificates in a {@code CertPath} is zero based. If no
 208      * index has been set, -1 is returned.
 209      *
 210      * @return the index that has been set, or -1 if none has been set
 211      */
 212     public int getIndex() {
 213         return this.index;
 214     }
 215 
 216     /**
 217      * Returns the reason that the validation failed. The reason is
 218      * associated with the index of the certificate returned by
 219      * {@link #getIndex}.
 220      *
 221      * @return the reason that the validation failed, or
 222      *    {@code BasicReason.UNSPECIFIED} if a reason has not been
 223      *    specified
 224      *
 225      * @since 1.7
 226      */
 227     public Reason getReason() {
 228         return this.reason;
 229     }
 230 
 231     private void readObject(ObjectInputStream stream)
 232         throws ClassNotFoundException, IOException {
 233         stream.defaultReadObject();
 234         if (reason == null) {
 235             reason = BasicReason.UNSPECIFIED;
 236         }
 237         if (certPath == null && index != -1) {
 238             throw new InvalidObjectException("certpath is null and index != -1");
 239         }
 240         if (index < -1 ||
 241             (certPath != null && index >= certPath.getCertificates().size())) {
 242             throw new InvalidObjectException("index out of range");