Apex provides a number of built-in exception types that the runtime engine throws if errors are encountered during execution. You’ve seen the DmlException in the previous example. Here is a sample of some other built-in exceptions. For a complete list of built-in exception types, see Exception Class and Built-In Exceptions.
try { Merchandise__c m = new Merchandise__c(); insert m; } catch(DmlException e) { System.debug('The following exception has occurred: ' + e.getMessage()); }
try { List<Integer> li = new List<Integer>(); li.add(15); // This list contains only one element, // but we're attempting to access the second element // from this zero-based list. Integer i1 = li[0]; Integer i2 = li[1]; // Causes a ListException } catch(ListException le) { System.debug('The following exception has occurred: ' + le.getMessage()); }
try { String s; Boolean b = s.contains('abc'); // Causes a NullPointerException } catch(NullPointerException npe) { System.debug('The following exception has occurred: ' + npe.getMessage()); }
try { // This statement doesn't cause an exception, even though // we don't have a merchandise with name='XYZ'. // The list will just be empty. List<Merchandise__c> lm = [SELECT Name FROM Merchandise__c WHERE Name = 'XYZ']; // lm.size() is 0 System.debug(lm.size()); // However, this statement causes a QueryException because // we're assiging the return value to a Merchandise__c object // but no Merchandise is returned. Merchandise__c m = [SELECT Name FROM Merchandise__c WHERE Name = 'XYZ' LIMIT 1]; } catch(QueryException qe) { System.debug('The following exception has occurred: ' + qe.getMessage()); }
try { Invoice_Statement__c inv = new Invoice_Statement__c( Description__c='New Invoice'); insert inv; // Query the invoice we just inserted Invoice_Statement__c v = [SELECT Name FROM Invoice_Statement__c WHERE Id = :inv.Id]; // Causes an SObjectException because we didn't retrieve // the Description__c field. String s = v.Description__c; } catch(SObjectException se) { System.debug('The following exception has occurred: ' + se.getMessage()); }
Example
To find out what some of the common methods return, try running this example.
try { Merchandise__c m = [SELECT Name FROM Merchandise__c LIMIT 1]; // Causes an SObjectException because we didn't retrieve // the Total_Inventory__c field. Double inventory = m.Total_Inventory__c; } catch(Exception e) { System.debug('Exception type caught: ' + e.getTypeName()); System.debug('Message: ' + e.getMessage()); System.debug('Cause: ' + e.getCause()); // returns null System.debug('Line number: ' + e.getLineNumber()); System.debug('Stack trace: ' + e.getStackTraceString()); }
The output of all System.debug statements looks like the following:
17:38:04:149 USER_DEBUG [7]|DEBUG|Exception type caught: System.SObjectException
17:38:04:149 USER_DEBUG [8]|DEBUG|Message: SObject row was retrieved via SOQL without querying the requested field: Merchandise__c.Total_Inventory__c
17:38:04:150 USER_DEBUG [9]|DEBUG|Cause: null
17:38:04:150 USER_DEBUG [10]|DEBUG|Line number: 5
17:38:04:150 USER_DEBUG [11]|DEBUG|Stack trace: AnonymousBlock: line 5, column 1
The catch statement argument type is the generic Exception type. It caught the more specific SObjectException. You can verify that this is so by inspecting the return value of e.getTypeName() in the debug output. The output also contains other properties of the SObjectException, like the error message, the line number where the exception occurred, and the stack trace. You might be wondering why getCause returned null. This is because in our sample there was no previous exception (inner exception) that caused this exception. In Create Custom Exceptions, you’ll get to see an example where the return value of getCause is an actual exception.
Some exception types, such as DmlException, have specific exception methods that apply to only them and aren’t common to other exception types:
Example
Merchandise__c m1 = new Merchandise__c( Name='Coffeemaker', Description__c='Kitchenware', Price__c=25, Total_Inventory__c=1000); // Missing the Price and Total_Inventory fields Merchandise__c m2 = new Merchandise__c( Name='Coffeemaker B', Description__c='Kitchenware'); // Missing all required fields Merchandise__c m3 = new Merchandise__c(); Merchandise__c[] mList = new List<Merchandise__c>(); mList.add(m1); mList.add(m2); mList.add(m3); try { insert mList; } catch (DmlException de) { Integer numErrors = de.getNumDml(); System.debug('getNumDml=' + numErrors); for(Integer i=0;i<numErrors;i++) { System.debug('getDmlFieldNames=' + de.getDmlFieldNames(i)); System.debug('getDmlMessage=' + de.getDmlMessage(i)); } }
Note how the sample above didn’t include all the initial code in the try block. Only the portion of the code that could generate an exception is wrapped inside a try block, in this case the insert statement could return a DML exception in case the input data is not valid. The exception resulting from the insert operation is caught by the catch block that follows it. After executing this sample, you’ll see an output of System.debug statements similar to the following:
14:01:24:939 USER_DEBUG [20]|DEBUG|getNumDml=2
14:01:24:941 USER_DEBUG [23]|DEBUG|getDmlFieldNames=(Price, Total Inventory)
14:01:24:941 USER_DEBUG [24]|DEBUG|getDmlMessage=Required fields are missing: [Price, Total Inventory]
14:01:24:942 USER_DEBUG [23]|DEBUG|getDmlFieldNames=(Description, Price, Total Inventory)
14:01:24:942 USER_DEBUG [24]|DEBUG|getDmlMessage=Required fields are missing: [Description, Price, Total Inventory]
The number of DML failures is correctly reported as two since two items in our list fail insertion. Also, the field names that caused the failure, and the error message for each failed record is written to the output.