1 /* 2 * Copyright (c) 2003, 2006, 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.spi; 27 28 import java.sql.SQLException; 29 import javax.sql.rowset.*; 30 31 /** 32 * Indicates an error with the <code>SyncProvider</code> mechanism. This exception 33 * is created by a <code>SyncProvider</code> abstract class extension if it 34 * encounters violations in reading from or writing to the originating data source. 35 * <P> 36 * If it is implemented to do so, the <code>SyncProvider</code> object may also create a 37 * <code>SyncResolver</code> object and either initialize the <code>SyncProviderException</code> 38 * object with it at construction time or set it with the <code>SyncProvider</code> object at 39 * a later time. 40 * <P> 41 * The method <code>acceptChanges</code> will throw this exception after the writer 42 * has finished checking for conflicts and has found one or more conflicts. An 43 * application may catch a <code>SyncProviderException</code> object and call its 44 * <code>getSyncResolver</code> method to get its <code>SyncResolver</code> object. 45 * See the code fragment in the interface comment for 46 * <a href="SyncResolver.html"><code>SyncResolver</code></a> for an example. 47 * This <code>SyncResolver</code> object will mirror the <code>RowSet</code> 48 * object that generated the exception, except that it will contain only the values 49 * from the data source that are in conflict. All other values in the <code>SyncResolver</code> 50 * object will be <code>null</code>. 51 * <P> 52 * The <code>SyncResolver</code> object may be used to examine and resolve 53 * each conflict in a row and then go to the next row with a conflict to 54 * repeat the procedure. 55 * <P> 56 * A <code>SyncProviderException</code> object may or may not contain a description of the 57 * condition causing the exception. The inherited method <code>getMessage</code> may be 58 * called to retrieve the description if there is one. 59 * 60 * @author Jonathan Bruce 61 * @see javax.sql.rowset.spi.SyncFactory 62 * @see javax.sql.rowset.spi.SyncResolver 63 * @see javax.sql.rowset.spi.SyncFactoryException 64 * @since 1.5 65 */ 66 public class SyncProviderException extends java.sql.SQLException { 67 68 /** 69 * The instance of <code>javax.sql.rowset.spi.SyncResolver</code> that 70 * this <code>SyncProviderException</code> object will return when its 71 * <code>getSyncResolver</code> method is called. 72 */ 73 private SyncResolver syncResolver = null; 74 75 /** 76 * Creates a new <code>SyncProviderException</code> object without a detail message. 77 */ 78 public SyncProviderException() { 79 super(); 80 } 81 82 /** 83 * Constructs a <code>SyncProviderException</code> object with the specified 84 * detail message. 85 * 86 * @param msg the detail message 87 */ 88 public SyncProviderException(String msg) { 89 super(msg); 90 } 91 92 /** 93 * Constructs a <code>SyncProviderException</code> object with the specified 94 * <code>SyncResolver</code> instance. 95 * 96 * @param syncResolver the <code>SyncResolver</code> instance used to 97 * to process the synchronization conflicts 98 * @throws IllegalArgumentException if the <code>SyncResolver</code> object 99 * is <code>null</code>. 100 */ 101 public SyncProviderException(SyncResolver syncResolver) { 102 if (syncResolver == null) { 103 throw new IllegalArgumentException("Cannot instantiate a SyncProviderException " + 104 "with a null SyncResolver object"); 105 } else { 106 this.syncResolver = syncResolver; 107 } 108 } 109 110 /** 111 * Retrieves the <code>SyncResolver</code> object that has been set for 112 * this <code>SyncProviderException</code> object, or 113 * if none has been set, an instance of the default <code>SyncResolver</code> 114 * implementation included in the reference implementation. 115 * <P> 116 * If a <code>SyncProviderException</code> object is thrown, an application 117 * may use this method to generate a <code>SyncResolver</code> object 118 * with which to resolve the conflict or conflicts that caused the 119 * exception to be thrown. 120 * 121 * @return the <code>SyncResolver</code> object set for this 122 * <code>SyncProviderException</code> object or, if none has 123 * been set, an instance of the default <code>SyncResolver</code> 124 * implementation. In addition, the default <code>SyncResolver</code> 125 * implementation is also returned if the <code>SyncResolver()</code> or 126 * <code>SyncResolver(String)</code> constructors are used to instantiate 127 * the <code>SyncResolver</code> instance. 128 */ 129 public SyncResolver getSyncResolver() { 130 if (syncResolver != null) { 131 return syncResolver; 132 } else { 133 try { 134 syncResolver = new com.sun.rowset.internal.SyncResolverImpl(); 135 } catch (SQLException sqle) { 136 } 137 return syncResolver; 138 } 139 } 140 141 /** 142 * Sets the <code>SyncResolver</code> object for this 143 * <code>SyncProviderException</code> object to the one supplied. 144 * If the argument supplied is <code>null</code>, a call to the method 145 * <code>getSyncResolver</code> will return the default reference 146 * implementation of the <code>SyncResolver</code> interface. 147 * 148 * @param syncResolver the <code>SyncResolver</code> object to be set; 149 * cannot be <code>null</code> 150 * @throws IllegalArgumentException if the <code>SyncResolver</code> object 151 * is <code>null</code>. 152 * @see #getSyncResolver 153 */ 154 public void setSyncResolver(SyncResolver syncResolver) { 155 if (syncResolver == null) { 156 throw new IllegalArgumentException("Cannot set a null SyncResolver " + 157 "object"); 158 } else { 159 this.syncResolver = syncResolver; 160 } 161 } 162 163 static final long serialVersionUID = -939908523620640692L; 164 165 }