Apex Basics

Like all languages, the power of Apex is contained within a syntactical framework. In this section, you will learn the basics about writing Apex code. If you are familiar with other strongly-typed, object-based language, especially Java, you might be able to simply skim this section to learn the key portions of Apex grammar. Please note that this section is not intended to replace the depth of the Force Platform documentation, but rather to provide you with the essentials you need to create Force Platform code in this and subsequent chapters.

Apex Statements

Apex statements have several standard syntax conventions: Individual statements are ended by a semi-colon (;). Parentheses are used to group values, such as the variables for a method call, or the evaluated expression in a conditional statement. Braces, or curly brackets ({}), are used to indicate a block of code. You will become familiar with these conventions as you develop code in the course of this and the next few chapters. You can indicate comments with your code in one of two ways. A single line comment must start with two forward slashes (//), while a multi-line comment begins with /* and ends with */. All text within comments is ignored.

Apex Variables
Apex code frequently requires variables to hold data values within a class or trigger.To make a variable available within a method, you declare the variable with the following basic syntax
Type([]) variable_name (= initialization);

You must declare a variable in the code before you can reference it. Variable names are case insensitive within your code. The data type for a variable can be one of several options: A primitive data type - includes a variety of number and date data types, an ID that represents the internal Force Platform ID for a record, a string, an object, or Boolean, which can only contain values of true, false or null An sObject - a data object that references a standard or custom object defined in your Force Platform organization. A collection - covered later in this section. Another object type - frequently used with Visualforce object types, such as selectOptions. You can declare an array by including square brackets ([])after the Type declaration. A variable declaration can initialize the variable, using the equals (=) sign and a value, as in:
String myString = 'Sample';

If a variable does not have an initial value assigned, the variable has a value of null. Variable declarations can also use an access modifier at the start of the declaration. The access modifier identifies the visibility of the variable. There are three options for this modifier:

 private the variable is only visible locally. This setting is the default if no access modifier is specified. You can have a class nested within a class. By default, these nested classes are private, meaning they are only visible within the outer class. public the variable is visible within your application global the variable is visible to all Apex scripts A variable can also use the keyword final as part of the declaration, between the access modifier and the data type. The final keyword indicates that the variable can only have a value assigned once. You can create constants with the same syntax as declaring variables by preceding the declaration with the keywords static and final.You must assign a value to a constant when the constant is declared. Be aware that the only implicit data type conversions in Apex are between different numeric types.

Apex Expressions and Operators

Apex has a rich variety of operators that can be used in expressions. Apex uses the double equals sign (==)as a comparison operator. Please refer to the Force Platform Apex documentation for a complete listing and explanation of comparison operators. String comparisons use case insensitive values for characters, so that 'a' and 'A' are equal in those comparisons. Null values are thought of as the lowest string value, in terms of string comparisons. Voice of the Developer: String comparisons with the comparison operator (==) are case insensitive. This quality means that the following clause returns true:
'a' == 'A'

If you want to compare string values with case sensitivity, you can use the equals method for the string.To perform a case sensitive equality test, you use code like the following to return false:
String xx = 'a'; xx.equals('A');

Apex Data Objects

IApex variables that hold recods from data objects are referred to as sObjects. sObjects take on the structure of the Force Platform standard or custom object that is declared as their data type. You initialize an sObject with the following syntax:
sObject name = new sObject();

You can also create a variable with the generic sObject type that is assigned a specific sObject type when the variable is initialized. You typically assign values to any of the fields in an sObject in one of two ways. You can use a list of field names and values in the parens following the sObject assignment. For instance, creating a new Location__c record in a variable, with a value of Toledo for the name looks

like the following:

Location__c homeOffice = new Location__c(Name = 'Toledo');

You can also initialize an sObject through an SOQL statement, such as

Location__c offices = [select Name, Address__c, City__c, State_Province__c from Location__c ];

Take care to properly initialize any sObject variables you use in your code. If your code attempts to access a value in an uninitialized sObject, you get a run-time exception. Fields within an sObject are accessed through dot notation, as in the following:
Location.Name = 'Toledo';

Dot notation is also used to access related objects and their fields, described in more depth in the discussion of SOQL (Salesforce Object Query Language) in the next chapter. Be aware that every record in an sObject includes a read-only ID field. The ID field is the unique identifier for the individual recordunique across all records in your Force Platform organization. The value for this field is automatically assigned when a record is created through an insert.You will learn much more about working with Apex code and data in the next chapter.

Apex Collections
In addition to sObjects, Apex supports three different types of collections: lists, sets and maps. You use declaration syntax for any of these collections, such as:
List<dataType> name = new List<dataType>;

All collections share the following characteristics: Contain multiple data values Support a variety of methods Allow access to individual items within a collection with a value within brackets, such as:
sampleList[1] = Second';

No single collection can contain more than 1,000 items. If any collection exceeds this limit, the Force Platform will generate a run-time error. You can have collections of collections, with each individual collection containing 1,000 records. The three types of collections. lists, sets and maps, also have slightly different characteristics, as detailed in the following sections.

Apex Lists
A list is an unordered collection of values. Lists are declared with the initial number of items in the list, indicated by an integer within square brackets. The brackets are required when declaring a list, but the integer is not. A list declared without a size integer contains no elements. An array can be used to represent a one-dimensional list. You can assign values to a list as part of its declaration by using curly brackets, as in the following:
String[] myTowns = new List<String>{'Toledo', 'Maumee', 'Perrysburg'};

which is the equivalent of

List<String> myTowns = new List<String>{'Toledo', 'Maumee', 'Perrysburg'};

Apex Sets

A set is also an unordered collection of values, with an important difference. A set cannot contain duplicate values. If you attempt to insert a value into a set that already exists, the add method returns false. You can use this feature to achieve some of your logical requirements, as you will later in this chapter. You declare a set with syntax similar to declaring a list, as in
Set<String> myTowns = new Set<String>{'Toledo', 'Maumee', 'Perrysburg'};

Apex Maps
Maps are collections of key-value pairs. The key for a map entry must be a primitive data type, while the value can be a primitive sObject, Apex object, or collection. You can have up to five levels of collections within a map. You can assign key-value pairs to a map when you declare the map, with a syntax of the following:
Map<String, String> cityState = new Map<String, String> {'Toledo' => 'Ohio', 'Chicago' => 'Illinois', 'Ann Arbor' => 'Michigan'}

Maps require the use of methods to retrieve values, and map methods are slightly different from the common methods used by lists and sets. For more details, please refer to the Force Platform Apex documentation.

Apex Conditional Logic

Of course, like all programming languages, Apex includes syntax to implement conditional logic, otherwise known as IF THEN ELSE logic. The basic format for this type of code is the following:
if (Boolean_expression) Statement; else Statement;

Note that the Boolean must be within parentheses, even if it is a simple expression, and you need to have semi-colons to indicate the end of each statement in the conditional logic. The form shown above includes a single statement for each condition. Normally, you create multiple statements for a condition, requiring the use of curly braces to group the statements, as in the following:
if (Boolean_expression){ statement; statement; statement; statement;} else { statement; statement;} You can nest if statements, giving syntax similar to the following: if (Location.Name == 'Toronto'){ Location.country__c = 'Canada'; } else if {(Location.Name == 'London'){

Location.country__c = 'United Kingdom'; } else { Location.country__c = 'United States'; }

Apex Loops

Apex supports the three standard types of loops for implementing repeated actions: Do-while, While, and For loops.

Do-while Loops
A Do-while loop repeatedly executes a set of code statements. The syntax for the loop is as follows:
do { code_block; } while (Boolean_condition); while

The code within the curly braces executes and then the condition is evaluated. A Doloop always executes at least once.

While Loops
A While loop is like a do-while loop, except that the while condition is evaluated before any of the statements in the code are executed. Because of this, the code in a While loop might not be executed at all. The syntax for the While loop is as follows:
while (Boolean_condition) { code_block; };

For Loops
Apex support three types of For loops: traditional, list/set iteration, and SOQL. The traditional For loop uses the following syntax:
for (init_statement; exit_condition; increment_statement) { code_block; } The init_statement executes when the loop is first entered and can initialize more than one variable.The exit_condition is evaluated every time the loop executes. If the

condition evaluates to false, the loop ends. If the condition evaluates to true, the code_block executes, followed by the increment statement. A typical For loop of this variety is as follows:
for (Integer I = 0; I < 10 ; I++) { System.debug('Iteration ' + I); }

This loop prints a list to the debug console consisting of the word Iteration followed by the values of I, from 0 to 9. Apex also supports For loops that are based on the entries in a set or a list. The syntax is as follows:

for (variable : list_or_set) { code_block; } This For loop executes once for each entry in the initial list or set variable. This variable

must

be the same data type as the list or set. You can use this syntax to get the same results as the previous For loop with the following code:

Integer[] listInts = new Integer[]{0,1,2,3,4,5,6,7,8,9}; for (Integer i : listInts) { System.debug('Iteration ' + i); } Apex code also supports a very powerful For loop that is used in association with SOQL

statements to iterate through a set of results. This loop syntax is especially powerful since you can use it to circumvent limitations on the number of entries in a collection. You will learn all about this type of For loop in the next chapter, which focuses on using Apex with data sets.

Apex Exception Handling

Of course, we all write perfect code, first time through. At least, that's what we wake up every morning hoping to accomplisha hope that is normally dashed within the first 15 minutes of coding. Any of the Apex development environments parse your code before allowing the code to be saved. This enforcement means that your code is syntactically correct, but there is no guarantee that the code will not encounter error conditions at run-time. When an Apex trigger or class encounters an error at runtime, the Force Platform environment throws an exception and terminates the execution of the code immediately. You can include code that allows you to handle exceptions more gracefully with try/catch syntax. The form for try/catch syntax is as follows:
try { code_block; } catch (exception_type){ code_block; } finally { code_block; }

Whenever an exception is thrown in the code_block immediately following the keyword try, the execution drops out of that block. There are different types of Force Platform exceptions so you can have more than one
catch

block, with no more than one catch block for a particular type of exception. You can also define your own exception types. The code_block for a particular exception type is executed when an exception of that type is thrown. You can also specify the general exception type of Exception, catching any exceptions not intercepted by previous catch statementsbecause of this, a catch statement that uses the general Exception must be the last catch statement in the block. Once the code for the appropriate catch block runs, the code_block listed for the finally statement is run. The finally statement is not required.

The following example shows the outline of try/catch syntax for a code block involves some type of data interaction that throws a DmlException:
try { code_block; } catch (DmlException de){ System.debug('Data exception:'+ de.getMessage()); } catch (Exception e) { System.debug('General exception:'+ e.getMessage()); }

You can also throw exceptions explicitly in your code. You can learn more about the methods available for exception objects in the Force Platform Apex documentation. Proper error handling can make the difference between a good application and a great application. At minimum, enclose data access statements in a try/catch block to account for any data access problems or limit problems. The Apex classes and triggers supplied from Code Share include try/catch blocks around all the code in order to gracefully handle any unanticipated problems at run-time. Important: You do not have to worry about errors occurring because of changes in the structure of Force Platform objects in your Apex code. Once an object is used in a piece of Apex code, no one can change attributes of that object. If an error occurs in the execution of your code, and that error is not intercepted through the use of a try/catch block, the error message is shown to the user on the page and an email is sent to the person who is identified in the LastModifiedBy field for the class.