001 /*
002 * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.security.cert;
027
028 import java.security.GeneralSecurityException;
029
030 /**
031 * An exception indicating one of a variety of problems encountered when
032 * validating a certification path.
033 * <p>
034 * A <code>CertPathValidatorException</code> provides support for wrapping
035 * exceptions. The {@link #getCause getCause} method returns the throwable,
036 * if any, that caused this exception to be thrown.
037 * <p>
038 * A <code>CertPathValidatorException</code> may also include the
039 * certification path that was being validated when the exception was thrown
040 * and the index of the certificate in the certification path that caused the
041 * exception to be thrown. Use the {@link #getCertPath getCertPath} and
042 * {@link #getIndex getIndex} methods to retrieve this information.
043 *
044 * <p>
045 * <b>Concurrent Access</b>
046 * <p>
047 * Unless otherwise specified, the methods defined in this class are not
048 * thread-safe. Multiple threads that need to access a single
049 * object concurrently should synchronize amongst themselves and
050 * provide the necessary locking. Multiple threads each manipulating
051 * separate objects need not synchronize.
052 *
053 * @see CertPathValidator
054 *
055 * @version 1.18 05/05/07
056 * @since 1.4
057 * @author Yassir Elley
058 */
059 public class CertPathValidatorException extends
060 GeneralSecurityException {
061
062 private static final long serialVersionUID = -3083180014971893139L;
063
064 /**
065 * @serial the index of the certificate in the certification path
066 * that caused the exception to be thrown
067 */
068 private int index = -1;
069
070 /**
071 * @serial the <code>CertPath</code> that was being validated when
072 * the exception was thrown
073 */
074 private CertPath certPath;
075
076 /**
077 * Creates a <code>CertPathValidatorException</code> with
078 * no detail message.
079 */
080 public CertPathValidatorException() {
081 super ();
082 }
083
084 /**
085 * Creates a <code>CertPathValidatorException</code> with the given
086 * detail message. A detail message is a <code>String</code> that
087 * describes this particular exception.
088 *
089 * @param msg the detail message
090 */
091 public CertPathValidatorException(String msg) {
092 super (msg);
093 }
094
095 /**
096 * Creates a <code>CertPathValidatorException</code> that wraps the
097 * specified throwable. This allows any exception to be converted into a
098 * <code>CertPathValidatorException</code>, while retaining information
099 * about the wrapped exception, which may be useful for debugging. The
100 * detail message is set to (<code>cause==null ? null : cause.toString()
101 * </code>) (which typically contains the class and detail message of
102 * cause).
103 *
104 * @param cause the cause (which is saved for later retrieval by the
105 * {@link #getCause getCause()} method). (A <code>null</code> value is
106 * permitted, and indicates that the cause is nonexistent or unknown.)
107 */
108 public CertPathValidatorException(Throwable cause) {
109 super (cause);
110 }
111
112 /**
113 * Creates a <code>CertPathValidatorException</code> with the specified
114 * detail message and cause.
115 *
116 * @param msg the detail message
117 * @param cause the cause (which is saved for later retrieval by the
118 * {@link #getCause getCause()} method). (A <code>null</code> value is
119 * permitted, and indicates that the cause is nonexistent or unknown.)
120 */
121 public CertPathValidatorException(String msg, Throwable cause) {
122 super (msg, cause);
123 }
124
125 /**
126 * Creates a <code>CertPathValidatorException</code> with the specified
127 * detail message, cause, certification path, and index.
128 *
129 * @param msg the detail message (or <code>null</code> if none)
130 * @param cause the cause (or <code>null</code> if none)
131 * @param certPath the certification path that was in the process of
132 * being validated when the error was encountered
133 * @param index the index of the certificate in the certification path
134 * that caused the error (or -1 if not applicable). Note that
135 * the list of certificates in a <code>CertPath</code> is zero based.
136 * @throws IndexOutOfBoundsException if the index is out of range
137 * <code>(index < -1 || (certPath != null && index >=
138 * certPath.getCertificates().size())</code>
139 * @throws IllegalArgumentException if <code>certPath</code> is
140 * <code>null</code> and <code>index</code> is not -1
141 */
142 public CertPathValidatorException(String msg, Throwable cause,
143 CertPath certPath, int index) {
144 super (msg, cause);
145 if (certPath == null && index != -1) {
146 throw new IllegalArgumentException();
147 }
148 if (index < -1
149 || (certPath != null && index >= certPath
150 .getCertificates().size())) {
151 throw new IndexOutOfBoundsException();
152 }
153 this .certPath = certPath;
154 this .index = index;
155 }
156
157 /**
158 * Returns the certification path that was being validated when
159 * the exception was thrown.
160 *
161 * @return the <code>CertPath</code> that was being validated when
162 * the exception was thrown (or <code>null</code> if not specified)
163 */
164 public CertPath getCertPath() {
165 return this .certPath;
166 }
167
168 /**
169 * Returns the index of the certificate in the certification path
170 * that caused the exception to be thrown. Note that the list of
171 * certificates in a <code>CertPath</code> is zero based. If no
172 * index has been set, -1 is returned.
173 *
174 * @return the index that has been set, or -1 if none has been set
175 */
176 public int getIndex() {
177 return this.index;
178 }
179
180 }
|