      1 /*
      2  * Copyright (c) 2005, 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  * $Id: URIReferenceException.java,v 1.4 2005/05/10 15:47:42 mullan Exp $
     27  */
     28 package javax.xml.crypto;
     29
     30 import java.io.PrintStream;
     31 import java.io.PrintWriter;
     32 import javax.xml.crypto.dsig.keyinfo.RetrievalMethod;
     33
     34 /**
     35  * Indicates an exceptional condition thrown while dereferencing a
     36  * {@link URIReference}.
     37  *
     38  * <p>A {@code URIReferenceException} can contain a cause: another
     39  * throwable that caused this {@code URIReferenceException} to get thrown.
     40  *
     41  * @author Sean Mullan
     42  * @author JSR 105 Expert Group
     43  * @since 1.6
     44  * @see URIDereferencer#dereference(URIReference, XMLCryptoContext)
     45  * @see RetrievalMethod#dereference(XMLCryptoContext)
     46  */
     47 public class URIReferenceException extends Exception {
     48
     49     private static final long serialVersionUID = 7173469703932561419L;
     50
     51     /**
     52      * The throwable that caused this exception to get thrown, or null if this
     53      * exception was not caused by another throwable or if the causative
     54      * throwable is unknown.
     55      *
     56      * @serial
     57      */
     58     private Throwable cause;
     59
     60     private URIReference uriReference;
     61
     62     /**
     63      * Constructs a new {@code URIReferenceException} with
     64      * {@code null} as its detail message.
     65      */
     66     public URIReferenceException() {
     67         super();
     68     }
     69
     70     /**
     71      * Constructs a new {@code URIReferenceException} with the specified
     72      * detail message.
     73      *
     74      * @param message the detail message
     75      */
     76     public URIReferenceException(String message) {
     77         super(message);
     78     }
     79
     80     /**
     81      * Constructs a new {@code URIReferenceException} with the
     82      * specified detail message and cause.
     83      * <p>Note that the detail message associated with
     84      * {@code cause} is <i>not</i> automatically incorporated in
     85      * this exception's detail message.
     86      *
     87      * @param message the detail message
     88      * @param cause the cause (A {@code null} value is permitted, and
     89      *        indicates that the cause is nonexistent or unknown.)
     90      */
     91     public URIReferenceException(String message, Throwable cause) {
     92         super(message);
     93         this.cause = cause;
     94     }
     95
     96     /**
     97      * Constructs a new {@code URIReferenceException} with the
     98      * specified detail message, cause and {@code URIReference}.
     99      * <p>Note that the detail message associated with
    100      * {@code cause} is <i>not</i> automatically incorporated in
    101      * this exception's detail message.
    102      *
    103      * @param message the detail message
    104      * @param cause the cause (A {@code null} value is permitted, and
    105      *        indicates that the cause is nonexistent or unknown.)
    106      * @param uriReference the {@code URIReference} that was being
    107      *    dereferenced when the error was encountered
    108      * @throws NullPointerException if {@code uriReference} is
    109      *    {@code null}
    110      */
    111     public URIReferenceException(String message, Throwable cause,
    112         URIReference uriReference) {
    113         this(message, cause);
    114         if (uriReference == null) {
    115             throw new NullPointerException("uriReference cannot be null");
    116         }
    117         this.uriReference = uriReference;
    118     }
    119
    120     /**
    121      * Constructs a new {@code URIReferenceException} with the specified
    122      * cause and a detail message of {@code (cause==null ? null :
    123      * cause.toString())} (which typically contains the class and detail
    124      * message of {@code cause}).
    125      *
    126      * @param cause the cause (A {@code null} value is permitted, and
    127      *        indicates that the cause is nonexistent or unknown.)
    128      */
    129     public URIReferenceException(Throwable cause) {
    130         super(cause==null ? null : cause.toString());
    131         this.cause = cause;
    132     }
    133
    134     /**
    135      * Returns the {@code URIReference} that was being dereferenced
    136      * when the exception was thrown.
    137      *
    138      * @return the {@code URIReference} that was being dereferenced
    139      * when the exception was thrown, or {@code null} if not specified
    140      */
    141     public URIReference getURIReference() {
    142         return uriReference;
    143     }
    144
    145     /**
    146      * Returns the cause of this {@code URIReferenceException} or
    147      * {@code null} if the cause is nonexistent or unknown.  (The
    148      * cause is the throwable that caused this
    149      * {@code URIReferenceException} to get thrown.)
    150      *
    151      * @return the cause of this {@code URIReferenceException} or
    152      *    {@code null} if the cause is nonexistent or unknown.
    153      */
    154     public Throwable getCause() {
    155         return cause;
    156     }
    157
    158     /**
    159      * Prints this {@code URIReferenceException}, its backtrace and
    160      * the cause's backtrace to the standard error stream.
    161      */
    162     public void printStackTrace() {
    163         super.printStackTrace();
    164         //XXX print backtrace of cause
    165     }
    166
    167     /**
    168      * Prints this {@code URIReferenceException}, its backtrace and
    169      * the cause's backtrace to the specified print stream.
    170      *
    171      * @param s {@code PrintStream} to use for output
    172      */
    173     public void printStackTrace(PrintStream s) {
    174         super.printStackTrace(s);
    175         //XXX print backtrace of cause
    176     }
    177
    178     /**
    179      * Prints this {@code URIReferenceException}, its backtrace and
    180      * the cause's backtrace to the specified print writer.
    181      *
    182      * @param s {@code PrintWriter} to use for output
    183      */
    184     public void printStackTrace(PrintWriter s) {
    185         super.printStackTrace(s);
    186         //XXX print backtrace of cause
    187     }
    188 }