      1 /*
      2  * Copyright (c) 2005, 2021, 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     /**
     61      * The {@code URIReference} that was being dereferenced
     62      * when the exception was thrown, or {@code null} if not specified.
     63      */
     64     private URIReference uriReference;
     65
     66     /**
     67      * Constructs a new {@code URIReferenceException} with
     68      * {@code null} as its detail message.
     69      */
     70     public URIReferenceException() {
     71         super();
     72     }
     73
     74     /**
     75      * Constructs a new {@code URIReferenceException} with the specified
     76      * detail message.
     77      *
     78      * @param message the detail message
     79      */
     80     public URIReferenceException(String message) {
     81         super(message);
     82     }
     83
     84     /**
     85      * Constructs a new {@code URIReferenceException} with the
     86      * specified detail message and cause.
     87      * <p>Note that the detail message associated with
     88      * {@code cause} is <i>not</i> automatically incorporated in
     89      * this exception's detail message.
     90      *
     91      * @param message the detail message
     92      * @param cause the cause (A {@code null} value is permitted, and
     93      *        indicates that the cause is nonexistent or unknown.)
     94      */
     95     public URIReferenceException(String message, Throwable cause) {
     96         super(message);
     97         this.cause = cause;
     98     }
     99
    100     /**
    101      * Constructs a new {@code URIReferenceException} with the
    102      * specified detail message, cause and {@code URIReference}.
    103      * <p>Note that the detail message associated with
    104      * {@code cause} is <i>not</i> automatically incorporated in
    105      * this exception's detail message.
    106      *
    107      * @param message the detail message
    108      * @param cause the cause (A {@code null} value is permitted, and
    109      *        indicates that the cause is nonexistent or unknown.)
    110      * @param uriReference the {@code URIReference} that was being
    111      *    dereferenced when the error was encountered
    112      * @throws NullPointerException if {@code uriReference} is
    113      *    {@code null}
    114      */
    115     public URIReferenceException(String message, Throwable cause,
    116         URIReference uriReference) {
    117         this(message, cause);
    118         if (uriReference == null) {
    119             throw new NullPointerException("uriReference cannot be null");
    120         }
    121         this.uriReference = uriReference;
    122     }
    123
    124     /**
    125      * Constructs a new {@code URIReferenceException} with the specified
    126      * cause and a detail message of {@code (cause==null ? null :
    127      * cause.toString())} (which typically contains the class and detail
    128      * message of {@code cause}).
    129      *
    130      * @param cause the cause (A {@code null} value is permitted, and
    131      *        indicates that the cause is nonexistent or unknown.)
    132      */
    133     public URIReferenceException(Throwable cause) {
    134         super(cause==null ? null : cause.toString());
    135         this.cause = cause;
    136     }
    137
    138     /**
    139      * Returns the {@code URIReference} that was being dereferenced
    140      * when the exception was thrown.
    141      *
    142      * @return the {@code URIReference} that was being dereferenced
    143      * when the exception was thrown, or {@code null} if not specified
    144      */
    145     public URIReference getURIReference() {
    146         return uriReference;
    147     }
    148
    149     /**
    150      * Returns the cause of this {@code URIReferenceException} or
    151      * {@code null} if the cause is nonexistent or unknown.  (The
    152      * cause is the throwable that caused this
    153      * {@code URIReferenceException} to get thrown.)
    154      *
    155      * @return the cause of this {@code URIReferenceException} or
    156      *    {@code null} if the cause is nonexistent or unknown.
    157      */
    158     public Throwable getCause() {
    159         return cause;
    160     }
    161
    162     /**
    163      * Prints this {@code URIReferenceException}, its backtrace and
    164      * the cause's backtrace to the standard error stream.
    165      */
    166     public void printStackTrace() {
    167         super.printStackTrace();
    168         //XXX print backtrace of cause
    169     }
    170
    171     /**
    172      * Prints this {@code URIReferenceException}, its backtrace and
    173      * the cause's backtrace to the specified print stream.
    174      *
    175      * @param s {@code PrintStream} to use for output
    176      */
    177     public void printStackTrace(PrintStream s) {
    178         super.printStackTrace(s);
    179         //XXX print backtrace of cause
    180     }
    181
    182     /**
    183      * Prints this {@code URIReferenceException}, its backtrace and
    184      * the cause's backtrace to the specified print writer.
    185      *
    186      * @param s {@code PrintWriter} to use for output
    187      */
    188     public void printStackTrace(PrintWriter s) {
    189         super.printStackTrace(s);
    190         //XXX print backtrace of cause
    191     }
    192 }
    --- EOF ---