Java > Open Source Codes > org > apache > derby > iapi > error > StandardException


1 /*
2
3    Derby - Class org.apache.derby.iapi.error.StandardException
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
11
12       http://www.apache.org/licenses/LICENSE-2.0
13
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */
21
22 package org.apache.derby.iapi.error;
23
24 import org.apache.derby.iapi.reference.SQLState;
25
26 import org.apache.derby.impl.jdbc.EmbedSQLException;
27 import org.apache.derby.iapi.error.ExceptionSeverity;
28 import org.apache.derby.iapi.services.i18n.MessageService;
29 import org.apache.derby.iapi.services.sanity.SanityManager;
30
31 import java.sql.SQLException ;
32 import java.sql.SQLWarning ;
33
34 /**
35     StandardException is the root of all exceptions that are handled
36     in a standard fashion by the database code, mainly in the language code.
37     <P>
38     This class is abstract to ensure that an implementation only throws
39     a specific exception (e.g. TransactionException) which is a sub-class
40     <P>
41     A method in an iterface in a protocol under com.ibm.db2j.protocol.Database must
42     only throw a StandardException (if it needs to throw an exception).
43     This indicates that the method can throw an exception and therefore its
44     caller must ensure that any resources it allocates will be cleaned up
45     in the event of an exception in the StandardException hierarchy.
46     <P>
47     Implementations of methods that throw StandardException can have throws
48     clause that are more specific than StandardException.
49 */
50
51 public class StandardException extends Exception
52 {
53     public static final int REPORT_DEFAULT = 0;
54     public static final int REPORT_NEVER = 1;
55     public static final int REPORT_ALWAYS = 2;
56
57     /*
58      * Exception State
59      */
60     private Throwable nestedException;
61     private transient Object [] arguments;
62     private int severity;
63     private String textMessage;
64     private String sqlState;
65     private transient int report;
66
67     /*
68     ** End of constructors
69     */
70     
71     protected StandardException(String messageID)
72     {
73         this(messageID, (Throwable ) null, (Object []) null);
74
75     }
76
77     protected StandardException(String messageID, Object [] args)
78     {
79         this(messageID, (Throwable ) null, args);
80     }
81
82     protected StandardException(String messageID, Throwable t, Object [] args)
83     {
84         super(messageID);
85
86         this.severity = getSeverityFromIdentifier(messageID);
87         this.sqlState = getSQLStateFromIdentifier(messageID);
88         this.nestedException = t;
89         this.arguments = args;
90
91         if (SanityManager.DEBUG)
92         {
93                     SanityManager.ASSERT(messageID != null,
94                                          "StandardException with no messageID");
95         }
96     }
97
98     /**
99      * This constructor is used when we already have the
100      * message text.
101      *
102      * @param sqlState the sql state of the message
103      * @param text the text of the message
104      */
105     private StandardException(String sqlState, String text)
106     {
107         this(sqlState);
108         textMessage = text;
109     }
110
111     /*
112     ** End of constructors
113     */
114     /**
115      * Sets the arguments for this exception.
116      */
117     private final void setArguments(Object [] arguments)
118     {
119         this.arguments = arguments;
120     }
121
122     /**
123      * Returns the arguments for this exception,
124      * if there are any.
125      */
126     public final Object [] getArguments()
127     {
128         return arguments;
129     }
130
131     /**
132      * Sets the nested exception for this exception.
133      */
134     public final void setNestedException(Throwable nestedException)
135     {
136         this.nestedException = nestedException;
137     }
138
139     /**
140      * Returns the nested exception for this exception,
141      * if there is one.
142      */
143     public final Throwable getNestedException()
144     {
145         return nestedException;
146     }
147
148     /**
149         Yes, report me. Errors that need this method to return
150         false are in the minority.
151     */
152     public final int report() {
153         return report;
154     }
155
156     /**
157         Set my report type.
158     */
159     public final void setReport(int report) {
160         this.report = report;
161     }
162
163     public final void setSeverity(int severity) {
164         this.severity = severity;
165     }
166
167
168     public final int getSeverity() {
169         return severity;
170     }
171
172     public final int getErrorCode() {
173         return severity;
174     }
175
176     /**
177         Return the 5 character SQL State.
178         If you need teh identifier that was used to create the
179         message, then use getMessageId(). getMessageId() will return the
180         string that corresponds to the field in org.apache.derby.iapi.reference.SQLState.
181     */
182     public final String getSQLState()
183     {
184         return sqlState;
185     }
186
187     /**
188         Convert a message identifer from org.apache.derby.iapi.reference.SQLState to
189         a SQLState five character string.
190      * @param messageID - the sql state id of the message from cloudscape
191      * @return String - the 5 character code of the SQLState ID to returned to the user
192     */
193     public static String getSQLStateFromIdentifier(String messageID) {
194
195         if (messageID.length() == 5)
196             return messageID;
197         return messageID.substring(0, 5);
198     }
199
200     /**
201         Get the severity given a message identifier from org.apache.derby.iapi.reference.SQLState.
202     */
203     public static int getSeverityFromIdentifier(String messageID) {
204
205         int lseverity = ExceptionSeverity.NO_APPLICABLE_SEVERITY;
206
207         switch (messageID.length()) {
208         case 5:
209             switch (messageID.charAt(0)) {
210             case '0':
211                 switch (messageID.charAt(1)) {
212                 case '1':
213                     lseverity = ExceptionSeverity.WARNING_SEVERITY;
214                     break;
215                 case 'A':
216                 case '7':
217                     lseverity = ExceptionSeverity.STATEMENT_SEVERITY;
218                     break;
219                 case '8':
220                     lseverity = ExceptionSeverity.SESSION_SEVERITY;
221                     break;
222                 }
223                 break;
224             case '2':
225             case '3':
226                 lseverity = ExceptionSeverity.STATEMENT_SEVERITY;
227                 break;
228             case '4':
229                 switch (messageID.charAt(1)) {
230                 case '0':
231                     lseverity = ExceptionSeverity.TRANSACTION_SEVERITY;
232                     break;
233                 case '2':
234                     lseverity = ExceptionSeverity.STATEMENT_SEVERITY;
235                     break;
236                 }
237                 break;
238             }
239             break;
240
241         default:
242             switch (messageID.charAt(6)) {
243             case 'M':
244                 lseverity = ExceptionSeverity.SYSTEM_SEVERITY;
245                 break;
246             case 'D':
247                 lseverity = ExceptionSeverity.DATABASE_SEVERITY;
248                 break;
249             case 'C':
250                 lseverity = ExceptionSeverity.SESSION_SEVERITY;
251                 break;
252             case 'T':
253                 lseverity = ExceptionSeverity.TRANSACTION_SEVERITY;
254                 break;
255             case 'S':
256                 lseverity = ExceptionSeverity.STATEMENT_SEVERITY;
257                 break;
258             case 'U':
259                 lseverity = ExceptionSeverity.NO_APPLICABLE_SEVERITY;
260                 break;
261             }
262             break;
263         }
264
265         return lseverity;
266     }
267
268     /*
269     ** Set of static methods to obtain exceptions.
270     **
271     ** Possible parameters:
272     ** String sqlState - SQL State
273     ** int severity - Severity of message
274     ** Throwable t - exception to wrap
275     ** Object aN - argument to error message
276     **
277     ** Calls that can be made after the exception has been created.
278     **
279     ** setExceptionCategory()
280     ** setReport()
281     */
282
283     /* specific exceptions */
284
285     public static StandardException normalClose()
286     {
287         StandardException se = newException( SQLState.NORMAL_CLOSE );
288         se.report = REPORT_NEVER;
289         return se;
290     }
291
292     /* 0 arguments */
293
294     public static StandardException newException(String messageID) {
295         return new StandardException(messageID);
296     }
297     public static StandardException newException(String messageID, Throwable t) {
298         return new StandardException(messageID, t, (Object []) null);
299     }
300
301     /* 1 argument */
302
303     public static StandardException newException(String messageID, Object a1) {
304         Object [] oa = new Object [] {a1};
305         return new StandardException(messageID, oa);
306     }
307     public static StandardException newException(String messageID, Throwable t, Object a1) {
308         Object [] oa = new Object [] {a1};
309         return new StandardException(messageID, t, oa);
310     }
311
312     /* 2 arguments */
313
314     public static StandardException newException(String messageID, Object a1, Object a2) {
315         Object [] oa = new Object [] {a1, a2};
316         return new StandardException(messageID, oa);
317     }
318
319     /**
320      * Dummy exception to catch incorrect use of
321      * StandardException.newException(), at compile-time. If you get a
322      * compilation error because this exception isn't caught, it means
323      * that you are using StandardException.newException(...)
324      * incorrectly. The nested exception should always be the second
325      * argument.
326      * @see StandardException#newException(String, Object, Throwable)
327      * @see StandardException#newException(String, Object, Object, Throwable)
328      */
329     public static class BadMessageArgumentException extends Throwable {}
330
331     /**
332      * Dummy overload which should never be called. Only used to
333      * detect incorrect usage, at compile time.
334      * @param messageID - the sql state id of the message
335      * @param a1 - Message arg
336      * @param t - Incorrectly placed exception to be nested
337      * @return nothing - always throws
338      * @throws BadMessageArgumentException - always (dummy)
339      */
340     public static StandardException newException(String messageID,
341                                                  Object a1,
342                                                  Throwable t)
343         throws BadMessageArgumentException {
344         throw new BadMessageArgumentException();
345     }
346
347     public static StandardException newException(String messageID, Throwable t, Object a1, Object a2) {
348         Object [] oa = new Object [] {a1, a2};
349         return new StandardException(messageID, t, oa);
350     }
351
352     /* 3 arguments */
353
354     public static StandardException newException(String messageID, Object a1, Object a2, Object a3) {
355         Object [] oa = new Object [] {a1, a2, a3};
356         return new StandardException(messageID, oa);
357     }
358     
359     /**
360      * Dummy overload which should never be called. Only used to
361      * detect incorrect usage, at compile time.
362      * @param messageID - the sql state id of the message
363      * @param a1 - First message arg
364      * @param a2 - Second message arg
365      * @param t - Incorrectly placed exception to be nested
366      * @return nothing - always throws
367      * @throws BadMessageArgumentException - always (dummy)
368      */
369     public static StandardException newException(String messageID,
370                                                  Object a1,
371                                                  Object a2,
372                                                  Throwable t)
373         throws BadMessageArgumentException {
374         throw new BadMessageArgumentException();
375     }
376
377     public static StandardException newException(String messageID, Throwable t, Object a1, Object a2, Object a3) {
378         Object [] oa = new Object [] {a1, a2, a3};
379         return new StandardException(messageID, t, oa);
380     }
381
382     /* 4 arguments */
383
384     public static StandardException newException(String messageID, Object a1, Object a2, Object a3, Object a4) {
385         Object [] oa = new Object [] {a1, a2, a3, a4};
386         return new StandardException(messageID, oa);
387     }
388     public static StandardException newException(String messageID, Throwable t, Object a1, Object a2, Object a3, Object a4) {
389         Object [] oa = new Object [] {a1, a2, a3, a4};
390         return new StandardException(messageID, t, oa);
391     }
392  
393     /* 5 arguments */
394     public static StandardException newException(String messageID, Object a1, Object a2, Object a3, Object a4, Object a5) {
395         Object [] oa = new Object [] {a1, a2, a3, a4, a5};
396         return new StandardException(messageID, oa);
397     }
398     public static StandardException newException(String messageID, Throwable t, Object a1, Object a2, Object a3, Object a4, Object a5) {
399         Object [] oa = new Object [] {a1, a2, a3, a4, a5};
400         return new StandardException(messageID, t, oa);
401     }
402
403     /* 6 arguments */
404     public static StandardException newException(String messageID, Object a1, Object a2, Object a3, Object a4, Object a5, Object a6) {
405         Object [] oa = new Object [] {a1, a2, a3, a4, a5, a6};
406         return new StandardException(messageID, oa);
407     }
408     public static StandardException newException(String messageID, Throwable t, Object a1, Object a2, Object a3, Object a4, Object a5, Object a6) {
409         Object [] oa = new Object [] {a1, a2, a3, a4, a5, a6};
410         return new StandardException(messageID, t, oa);
411     }
412
413     /* 7 arguments */
414     public static StandardException newException(String messageID, Object a1, Object a2, Object a3, Object a4, Object a5, Object a6, Object a7) {
415         Object [] oa = new Object [] {a1, a2, a3, a4, a5, a6, a7};
416         return new StandardException(messageID, oa);
417     }
418     public static StandardException newException(String messageID, Throwable t, Object a1, Object a2, Object a3, Object a4, Object a5, Object a6, Object a7) {
419         Object [] oa = new Object [] {a1, a2, a3, a4, a5, a6, a7};
420         return new StandardException(messageID, t, oa);
421     }
422
423     /* 8 arguments */
424     public static StandardException newException(String messageID, Object a1, Object a2, Object a3, Object a4, Object a5, Object a6, Object a7, Object a8) {
425         Object [] oa = new Object [] {a1, a2, a3, a4, a5, a6, a7, a8};
426         return new StandardException(messageID, oa);
427     }
428     public static StandardException newException(String messageID, Throwable t, Object a1, Object a2, Object a3, Object a4, Object a5, Object a6, Object a7, Object a8) {
429         Object [] oa = new Object [] {a1, a2, a3, a4, a5, a6, a7, a8};
430         return new StandardException(messageID, t, oa);
431     }
432
433     /**
434      * Creates a new StandardException using message text that has already been localized.
435      *
436      * @param MessageID The SQLState and severity are derived from the ID. However the text message is not.
437      * @param t The Throwable that caused this exception, null if this exception was not caused by another Throwable.
438      * @param localizedMessage The message associated with this exception.
439      * <b>It is the caller's responsibility to ensure that this message is properly localized.</b>
440      *
441      * See org.apache.derby.iapi.tools.i18n.LocalizedResource
442      */
443     public static StandardException newPreLocalizedException( String MessageID,
444                                                               Throwable t,
445                                                               String localizedMessage)
446     {
447         StandardException se = new StandardException( MessageID, localizedMessage);
448         if( t != null)
449             se.nestedException = t;
450         return se;
451     }
452
453     public static StandardException unexpectedUserException(Throwable t)
454     {
455         /*
456         ** If we have a SQLException that isn't a Util
457         ** (i.e. it didn't come from cloudscape), then we check
458         ** to see if it is a valid user defined exception range
459         ** (38001-38XXX). If so, then we convert it into a
460         ** StandardException without further ado.
461         */
462         if ((t instanceof SQLException) &&
463             !(t instanceof EmbedSQLException))
464         {
465             SQLException sqlex = (SQLException)t;
466             String state = sqlex.getSQLState();
467             if ((state != null) &&
468                 (state.length() == 5) &&
469                 state.startsWith("38") &&
470                 !state.equals("38000"))
471             {
472                 StandardException se = new StandardException(state, sqlex.getMessage());
473                 if (sqlex.getNextException() != null)
474                 {
475                     se.setNestedException(sqlex.getNextException());
476                 }
477                 return se;
478             }
479         }
480
481         // Look for simple wrappers for 3.0.1 - will be cleaned up in main
482 if (t instanceof EmbedSQLException) {
483             EmbedSQLException csqle = (EmbedSQLException) t;
484             if (csqle.isSimpleWrapper()) {
485                 Throwable wrapped = csqle.getJavaException();
486                 if (wrapped instanceof StandardException)
487                     return (StandardException) wrapped;
488             }
489         }
490
491
492         // no need to wrap a StandardException
493 if (t instanceof StandardException)
494         {
495             return (StandardException) t;
496         }
497         else
498         {
499             /*
500             **
501             ** The exception at this point could be a:
502             **
503             ** standard java exception, e.g. NullPointerException
504             ** SQL Exception - from some server-side JDBC
505             ** 3rd party exception - from some application
506             ** some cloudscape exception that is not a standard exception.
507             **
508             **
509             ** We don't want to call t.toString() here, because the JVM is
510             ** inconsistent about whether it includes a detail message
511             ** with some exceptions (esp. NullPointerException). In those
512             ** cases where there is a detail message, t.toString() puts in
513             ** a colon character, even when the detail message is blank.
514             ** So, we do our own string formatting here, including the colon
515             ** only when there is a non-blank message.
516             **
517             ** The above is because our test canons contain the text of
518             ** error messages.
519             **
520             ** In addition we don't want to place the class name in an
521             ** exception when the class is from cloudscape because
522             ** the class name changes in obfuscated builds. Thus for
523             ** exceptions that are in a package below com.ibm.db2j
524             ** we use toString(). If this returns an empty or null
525             ** then we use the class name to make tracking the problem
526             ** down easier, though the lack of a message should be seen
527             ** as a bug.
528             */
529             String detailMessage;
530             boolean cloudscapeException = false;
531
532             if (t instanceof EmbedSQLException) {
533                 detailMessage = ((EmbedSQLException) t).toString();
534                 cloudscapeException = true;
535             }
536             else {
537                 detailMessage = t.getMessage();
538             }
539
540             if (detailMessage == null)
541             {
542                 detailMessage = "";
543             } else {
544                 detailMessage = detailMessage.trim();
545             }
546
547             // if no message, use the class name
548 if (detailMessage.length() == 0) {
549                 detailMessage = t.getClass().getName();
550             }
551             else {
552
553                 if (!cloudscapeException) {
554                     detailMessage = t.getClass().getName() + ": " + detailMessage;
555                 }
556             }
557
558             StandardException se =
559                 newException(SQLState.LANG_UNEXPECTED_USER_EXCEPTION, t, detailMessage);
560             return se;
561         }
562     }
563
564     /**
565         Similar to unexpectedUserException but makes no assumtion about
566         when the execption is being called. The error is wrapped as simply
567         as possible.
568     */
569
570     public static StandardException plainWrapException(Throwable t) {
571
572         if (t instanceof StandardException)
573             return (StandardException) t;
574
575         if (t instanceof SQLException) {
576
577             SQLException sqle = (SQLException) t;
578
579             String sqlState = sqle.getSQLState();
580             if (sqlState != null) {
581
582                 StandardException se = new StandardException(sqlState, "(" + sqle.getErrorCode() + ") " + sqle.getMessage());
583                 sqle = sqle.getNextException();
584                 if (sqle != null)
585                     se.setNestedException(plainWrapException(sqle));
586                 return se;
587             }
588         }
589
590         String detailMessage = t.getMessage();
591
592         if (detailMessage == null)
593         {
594             detailMessage = "";
595         } else {
596             detailMessage = detailMessage.trim();
597         }
598         
599         StandardException se =
600                 newException(SQLState.JAVA_EXCEPTION, t, detailMessage, t.getClass().getName());
601         return se;
602     }
603
604     /**
605     ** A special exception to close a session.
606     */
607     public static StandardException closeException() {
608         StandardException se = newException(SQLState.CLOSE_REQUEST);
609         se.setReport(REPORT_NEVER);
610         return se;
611     }
612     /*
613     ** Message handling
614     */
615
616     /**
617         The message stored in the super class Throwable must be set
618         up object creation. At this time we cannot get any information
619         about the object itself (ie. this) in order to determine the
620         natural language message. Ie. we need to class of the objec in
621         order to look up its message, but we can't get the class of the
622         exception before calling the super class message.
623         <P>
624         Thus the message stored by Throwable and obtained by the
625         getMessage() of Throwable (ie. super.getMessage() in this
626         class) is the message identifier. The actual text message
627         is stored in this class at the first request.
628
629     */
630
631     public String getMessage() {
632         if (textMessage == null)
633             textMessage = MessageService.getCompleteMessage(getMessageId(), getArguments());
634
635         return textMessage;
636     }
637
638     /**
639         Return the message identifier that is used to look up the
640         error message text in the messages.properties file.
641     */
642     public final String getMessageId() {
643         return super.getMessage();
644     }
645
646
647     /**
648         Get the error code for an error given a type. The value of
649         the property messageId.type will be returned, e.g.
650         deadlock.sqlstate.
651     */
652     public String getErrorProperty(String type) {
653         return getErrorProperty(getMessageId(), type);
654     }
655
656     /**
657         Don't print the class name in the toString() method.
658     */
659     public String toString() {
660         String msg = getMessage();
661
662         return "ERROR " + getSQLState() + ": " + msg;
663     }
664
665     /*
666     ** Static methods
667     */
668
669     private static String getErrorProperty(String messageId, String type) {
670         return MessageService.getProperty(messageId, type);
671     }
672
673     public static StandardException interrupt(InterruptedException ie) {
674         StandardException se = StandardException.newException(SQLState.CONN_INTERRUPT, ie);
675         return se;
676     }
677     /*
678     ** SQL warnings
679     */
680
681     public static SQLWarning newWarning(String messageId) {
682
683         return newWarningCommon( messageId, (Object []) null );
684
685     }
686
687     public static SQLWarning newWarning(String messageId, Object a1) {
688
689         Object [] oa = new Object [] {a1};
690
691         return newWarningCommon( messageId, oa );
692     }
693
694     public static SQLWarning newWarning(String messageId, Object a1, Object a2) {
695
696         Object [] oa = new Object [] {a1, a2};
697
698         return newWarningCommon( messageId, oa );
699     }
700
701     private static SQLWarning newWarningCommon( String messageId, Object [] oa )
702     {
703         String message = MessageService.getCompleteMessage(messageId, oa);
704         String state = StandardException.getSQLStateFromIdentifier(messageId);
705         SQLWarning sqlw = new SQLWarning (message, state, ExceptionSeverity.WARNING_SEVERITY);
706
707         return sqlw;
708     }
709 }
710

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags