Microsoft Dynamic AX 2009 : The Database Layer – Database-Triggering Methods (part 1) – insert, update, and delete Methods

A record buffer contains a variety of instance methods, and when called directly or indirectly, it results in statements or affects the number of statements sent to the database. Some of the methods can be called explicitly, and some are called implicitly by the Dynamics AX application runtime. Some of the methods are final, and others can be overridden. All the base versions of these methods are implemented on the xRecord system class. In this section, we provide an overview of these methods and describe how the Dynamics AX application runtime interprets the execution of these methods and other built-in constructs in X++. We also explain how this interpretation results in different SQL statements being passed to the database for execution.

1. insert, update, and delete Methods

The three main methods used on the record buffer to manipulate data in the database are insert, update, and delete. When called, each method results in an INSERT, an UPDATE, or a DELETE statement being passed from the AOS to the database where each statement manipulates a single row.

You can override all three methods on each table individually, as shown for the insert method in the following code. You follow the same pattern for update and delete. The super call to the base class method makes the application runtime formulate the SQL DML statement and passes it to the database. Consequently, when you override one of these methods, the application can execute additional X++ code before or after the statement is passed to the database.

public void insert()
{
    // Additional code before insertion record
    super(); // The SQL statement is formulated when executing super();
    // Additional code after insertion of record
}

Although none of the three methods explicitly contains the server or client method modifier, they all are always executed on the tier where the data source is located. The methods are executed on the server tier, but the methods on a temporary table can be executed on either the client tier or the server tier. Applying the server or client method modifier to these methods doesn’t change this behavior.

There are also three equivalent methods for inserting, updating, and deleting: doInsert, doUpdate, and doDelete. Each method executes the same run-time logic as the base class version of the insert, update, and delete methods; using these methods circumvents any X++ logic in the overridden versions of insert, update, and delete, so use them with caution. The doInsert, doUpdate, and doDelete methods can’t be overridden.

The record buffer also contains a write method that can be overridden. The execution of this methods leads to the execution of either the update method or the insert method, depending on whether the record has already been inserted.

As with the insert, update, and delete methods, write is forced by the application runtime to execute on the tier where the data source is located, no matter what is stated in the definition of the method.

2. Selecting Rows

The record buffer also contains the overridable method postLoad. You don’t need to execute postLoad from X++ because the application runtime executes it when the AOS retrieves records from the database. When you override postLoad, the super call copies the retrieved buffer to the original record buffer that is accessible through the orig method. Before an overridden postLoad method calls the base class method, the state of the original buffer is undefined.

The application runtime also forces postLoad to execute on the tier where the data source is located. Assuming that the table isn’t temporary and a client retrieves multiple records, postLoad executes on all the retrieved records sent from the database to the AOS before the AOS sends them individually to the client.

3. Validating Rows

The record buffer contains two sets of validation methods that can be overridden: the validateField, validateWrite, and validateDelete methods and the aosValidateRead, aosValidateInsert, aosValidateUpdate, and aosValidateDelete methods, which were introduced in Dynamics AX 4.0.

The difference between the two sets of methods is that validateField, validateWrite, and validateDelete are invoked only from rich client and Web client forms or if called directly from X++ code, whereas aosValidateInsert, aosValidateUpdate, and aosValidateDelete are invoked implicitly from the insert, update, and delete base version methods, respectively. The aosValidateRead method is invoked when the application retrieves records from the database.

The aosValidate methods prevent reading, writing, or deleting, so they should return a Boolean value of false if the user isn’t allowed to perform the operation that the method is validating. If the method returns false, an error is written to the Infolog, and the Dynamics AX application runtime throws an Exception::Error. The form application runtime also writes an error to the Infolog if any of the validate methods return false. When a validate method is called from X++ code, the calling method determines how to handle a validate method that returns false.

• Microsoft Dynamic AX 2009 : The Database Layer – Database-Triggering Methods (part 2) – Changing the Default Behavior