1 /*
   2  * Copyright (c) 2003, 2014, 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.sql.rowset;
  27 
  28 import java.sql.SQLException;
  29 
  30 /**
  31  * An extension of <code>SQLException</code> that provides information
  32  * about database warnings set on <code>RowSet</code> objects.
  33  * Warnings are silently chained to the object whose method call
  34  * caused it to be reported.
  35  * This class complements the <code>SQLWarning</code> class.
  36  * <P>
  37  * Rowset warnings may be retrieved from <code>JdbcRowSet</code>,
  38  * <code>CachedRowSet</code>&trade;,
  39  * <code>WebRowSet</code>, <code>FilteredRowSet</code>, or <code>JoinRowSet</code>
  40  * implementations. To retrieve the first warning reported on any
  41  * <code>RowSet</code>
  42  * implementation,  use the method <code>getRowSetWarnings</code> defined
  43  * in the <code>JdbcRowSet</code> interface or the <code>CachedRowSet</code>
  44  * interface. To retrieve a warning chained to the first warning, use the
  45  * <code>RowSetWarning</code> method
  46  * <code>getNextWarning</code>. To retrieve subsequent warnings, call
  47  * <code>getNextWarning</code> on each <code>RowSetWarning</code> object that is
  48  * returned.
  49  * <P>
  50  * The inherited methods <code>getMessage</code>, <code>getSQLState</code>,
  51  * and <code>getErrorCode</code> retrieve information contained in a
  52  * <code>RowSetWarning</code> object.
  53  *
  54  * @since 1.5
  55  */
  56 public class RowSetWarning extends SQLException {
  57 
  58     /**
  59      * RowSetWarning object handle.
  60      */
  61      private RowSetWarning rwarning;
  62 
  63     /**
  64      * Constructs a <code>RowSetWarning</code> object
  65      * with the given value for the reason; SQLState defaults to null,
  66      * and vendorCode defaults to 0.
  67      *
  68      * @param reason a <code>String</code> object giving a description
  69      *        of the warning; if the <code>String</code> is <code>null</code>,
  70      *        this constructor behaves like the default (zero parameter)
  71      *        <code>RowSetWarning</code> constructor
  72      */
  73     public RowSetWarning(String reason) {
  74         super(reason);
  75     }
  76 
  77     /**
  78      * Constructs a default <code>RowSetWarning</code> object. The reason
  79      * defaults to <code>null</code>, SQLState defaults to null and vendorCode
  80      * defaults to 0.
  81      */
  82     public RowSetWarning() {
  83         super();
  84     }
  85 
  86     /**
  87      * Constructs a <code>RowSetWarning</code> object initialized with the
  88      * given values for the reason and SQLState. The vendor code defaults to 0.
  89      *
  90      * If the <code>reason</code> or <code>SQLState</code> parameters are <code>null</code>,
  91      * this constructor behaves like the default (zero parameter)
  92      * <code>RowSetWarning</code> constructor.
  93      *
  94      * @param reason a <code>String</code> giving a description of the
  95      *        warning;
  96      * @param SQLState an XOPEN code identifying the warning; if a non standard
  97      *        XOPEN <i>SQLState</i> is supplied, no exception is thrown.
  98      */
  99     public RowSetWarning(java.lang.String reason, java.lang.String SQLState) {
 100         super(reason, SQLState);
 101     }
 102 
 103     /**
 104      * Constructs a fully specified <code>RowSetWarning</code> object initialized
 105      * with the given values for the reason, SQLState and vendorCode.
 106      *
 107      * If the <code>reason</code>, or the  <code>SQLState</code>
 108      * parameters are <code>null</code>, this constructor behaves like the default
 109      * (zero parameter) <code>RowSetWarning</code> constructor.
 110      *
 111      * @param reason a <code>String</code> giving a description of the
 112      *        warning;
 113      * @param SQLState an XOPEN code identifying the warning; if a non standard
 114      *        XOPEN <i>SQLState</i> is supplied, no exception is thrown.
 115      * @param vendorCode a database vendor-specific warning code
 116      */
 117     public RowSetWarning(java.lang.String reason, java.lang.String SQLState, int vendorCode) {
 118         super(reason, SQLState, vendorCode);
 119     }
 120 
 121     /**
 122      * Retrieves the warning chained to this <code>RowSetWarning</code>
 123      * object.
 124      *
 125      * @return the <code>RowSetWarning</code> object chained to this one; if no
 126      *         <code>RowSetWarning</code> object is chained to this one,
 127      *         <code>null</code> is returned (default value)
 128      * @see #setNextWarning
 129      */
 130     public RowSetWarning getNextWarning() {        
 131         try {
 132             return ((RowSetWarning)getNextException());
 133         } catch (ClassCastException ex) {
 134             // The chained value isn't a RowSetWarning.
 135             // This is a programming error by whoever added it to
 136             // the RowSetWarning chain.  We throw a Java "Error".
 137             throw new Error("RowSetWarning chain holds value that is not a RowSetWarning");
 138         }
 139         
 140     }
 141 
 142     /**
 143      * Sets <i>warning</i> as the next warning, that is, the warning chained
 144      * to this <code>RowSetWarning</code> object.
 145      *
 146      * @param warning the <code>RowSetWarning</code> object to be set as the
 147      *     next warning; if the <code>RowSetWarning</code> is null, this
 148      *     represents the finish point in the warning chain
 149      * @see #getNextWarning
 150      */
 151     public void setNextWarning(RowSetWarning warning) {
 152         setNextException(warning);
 153     }
 154 
 155     static final long serialVersionUID = 6678332766434564774L;
 156 }