1 /***
2 * SQLExceptionHandler.java
3 *
4 * This file is part of the creme library.
5 * The creme library intends to ease the development effort of large
6 * applications by providing easy to use support classes.
7 *
8 * Copyright (C) 2002 Denis Bregeon
9 *
10 *
11 * This library is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU Lesser General Public
13 * License as published by the Free Software Foundation; either
14 * version 2.1 of the License, or (at your option) any later version.
15 *
16 * This library is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with this library; if not, write to the Free Software
23 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
24 *
25 * contact information: dbregeon@sourceforge.net
26 */
27 package org.jcreme.sql;
28
29 import java.sql.SQLException;
30
31 /***
32 * This interface describes how to handle the exceptions. It enabled to apply
33 * specific actions depending on the type of Exception. A handler can centralize
34 * the actions to take in an application. Handlers can also be specialized by
35 * database vendor.
36 */
37 public interface SQLExceptionHandler {
38 /***
39 * Specifies that the exception was successfully handled.
40 */
41 public static final int WAS_HANDLED = 1;
42
43 /***
44 * Specifies that the exception type is not determined.
45 */
46 public static final int EXCEPTION_TYPE_UNKNOWN = 2;
47
48 /***
49 * Specifies that the exception signals a loss of connection.
50 */
51 public static final int EXCEPTION_TYPE_LOSS_OF_CONNECTION = 4;
52
53 /***
54 * Specifies that the exception signals a deadlock that provoked a rollback.
55 */
56 public static final int EXCEPTION_TYPE_ROLLEDBACK_DEADLOCK = 8;
57
58 /***
59 * Specifies that the exception signals a deadlock that did not provoke a
60 * rollback.
61 */
62 public static final int EXCEPTION_TYPE_PLAIN_DEADLOCK = 16;
63
64 /***
65 * This method handles an SQLException. There is no special handling of
66 * deadlocks.
67 *
68 * @param e
69 * the exception to handle.
70 * @return the type of the exception e.
71 */
72 public int handleException(SQLException e);
73
74 /***
75 * This method handles an SQLException. The rollback action is invoked if
76 * the exception is a rolled back deadlock.
77 *
78 * @param e
79 * the exception to handle.
80 * @param rollback
81 * the action to invoke to rollback.
82 * @param lossOfConnection
83 * the action to invoke in case of a loss of connection.
84 * @return the type of the exception e.
85 */
86 public int handleException(SQLException e, CremeAction rollback,
87 CremeAction lossOfConnection);
88
89 /***
90 * This method handles an SQLException. The rollback action is invoked if
91 * the exception is a rolled back deadlock. The redo action is invoked if
92 * the exception is a simple deadlock.
93 *
94 * @param e
95 * the exception to handle.
96 * @param rollback
97 * the action to invoke to rollback.
98 * @param lossOfConnection
99 * the action to invoke in case of a loss of connection.
100 * @param redo
101 * the action to invoke in case of a simple deadlock.
102 * @return the type of the exception e.
103 */
104 public int handleException(SQLException e, CremeAction rollback,
105 CremeAction lossOfConnection, CremeAction redo);
106
107 /***
108 * This method can be used to test a result returned by a handleException
109 * method call.
110 *
111 * @param i
112 * an int produced by a handleException method call.
113 * @return true if the exception was handled, false otherwise.
114 */
115 public boolean wasHandled(int i);
116
117 /***
118 * This method can be used to test a result returned by a handleException
119 * method call.
120 *
121 * @param i
122 * an int produced by a handleException method call.
123 * @return true if the type of the exception is not known, false otherwise.
124 */
125 public boolean isUnknown(int i);
126
127 /***
128 * This method can be used to test a result returned by a handleException
129 * method call.
130 *
131 * @param i
132 * an int produced by a handleException method call.
133 * @return true if the exception is a loss of connection, false otherwise.
134 */
135 public boolean isLossOfConnection(int i);
136
137 /***
138 * This method can be used to test a result returned by a handleException
139 * method call.
140 *
141 * @param i
142 * an int produced by a handleException method call.
143 * @return true if the exception is a deadlock and the transaction was
144 * rolled back, false otherwise.
145 */
146 public boolean isRolledBackDeadLock(int i);
147
148 /***
149 * This method can be used to test a result returned by a handleException
150 * method call.
151 *
152 * @param i
153 * an int produced by a handleException method call.
154 * @return true if the exception is a simple deadlock, false otherwise.
155 */
156 public boolean isPlainDeadLock(int i);
157
158 /***
159 * This method can be used to test an SQLException.
160 *
161 * @param e
162 * an SQLException to test.
163 * @return true if the exception is a loss of connection, false otherwise.
164 */
165 public boolean isLossOfConnection(SQLException e);
166
167 /***
168 * This method can be used to test an SQLException.
169 *
170 * @param e
171 * an SQLException to test.
172 * @return true if the exception is a deadlock and the transaction was
173 * rolled back, false otherwise.
174 */
175 public boolean isRolledBackDeadLock(SQLException e);
176
177 /***
178 * This method can be used to test an SQLException.
179 *
180 * @param e
181 * an SQLException to test.
182 * @return true if the exception is a simple deadlock, false otherwise.
183 */
184 public boolean isPlainDeadLock(SQLException e);
185
186 /***
187 * This method can be used to test an SQLException.
188 *
189 * @param e
190 * an SQLException to test.
191 * @return true if the exception is a deadlock (simple or not), false
192 * otherwise.
193 */
194 public boolean isDeadLock(SQLException e);
195
196 /***
197 * This method gives access to the number of attempts that will be done to
198 * resolve a deadlock (number of calls to the redo action).
199 *
200 * @return the number of attempts that will be done to resolve a deadlock.
201 */
202 public int getNumberOfTries();
203
204 /***
205 * This method enables to change the number of tries attempts that will be
206 * done to resolve a deadlock (number of calls to the redo action).
207 *
208 * @param number
209 * the number of attempts that will be done
210 */
211 public void setNumberOfTries(int number);
212
213 /***
214 * This method gives access to the number of milliseconds that the thread
215 * will wait for before making a new attempt to resolve a deadlock.
216 *
217 * @return the number of milliseconds that the thread will wait for before
218 * making a new attempt to resolve a deadlock.
219 */
220 public int getDeadlockTimeout();
221
222 /***
223 * This method enables to change the number of milliseconds that the thread
224 * will wait for before making a new attempt to resolve a deadlock.
225 *
226 * @param timeout
227 * the number of milliseconds that the thread will wait for
228 * before making a new attempt to resolve a deadlock.
229 */
230 public void setDeadlockTimeout(int timeout);
231 }