Art Of Creation - Dynamics AX Blog » Patterns

Try Catch example code

Klaas Deforche — Tue, 09 Aug 2011 18:04:50 +0000

Hi all!

The code below contains a try/catch that I use a lot when developing batch jobs, especially multithreaded ones.
It deals with frequently occurring exceptions that, in some cases, can be easily solved by retrying:

Deadlocks
Update conflicts
Duplicate key conflicts

Duplicate key conflicts are more rare than update conflicts, but I’ve seen them pop up under heavy load on InventDim records.

try
{
ttsbegin;

// do stuff here

ttsCommit;
}
catch (Exception::Deadlock)
{
// retry on deadlock
retry;
}
catch (Exception::UpdateConflict)
{
// try to resolve update conflict
if (appl.ttsLevel() == 0)
{
if (xSession::currentRetryCount() >= #RetryNum)
{
throw Exception::UpdateConflictNotRecovered;
}
else
{
retry;
}
}
else
{
throw Exception::UpdateConflict;
}
}
catch(Exception::DuplicateKeyException)
{
// retry in case of an duplicate key conflict
if (appl.ttsLevel() == 0)
{
if (xSession::currentRetryCount() >= #RetryNum)
{
throw Exception::DuplicateKeyExceptionNotRecovered;
}
else
{
retry;
}
}
else
{
throw Exception::DuplicateKeyException;
}
}

Creating a class, the best practice way

Klaas Deforche — Tue, 18 May 2010 11:40:20 +0000

Hi all!

Some time ago, I talked about the ‘construct’ pattern that is use a lot in AX. Although I use it often, it’s not perfect because it violates some best practices. (Also, you could end up with a large class hierarchy of classes that extend each other, but I’ll discuss that in an other post.)

First off, know that you can change the compiler level and the best practices the compiler checks.
To do this, compile something so the compiler output window pops up. Then click the setup button, and adjust the settings.
I used compiler level 4 and enabled all BP checks for this example.

So, let create a simple class. This class will simply print information of an InventTable record to the screen.

1. ClassDeclaration
When we think about this class a bit, we immediately realize that we need to declare an InventTable record as a member of out class:

///

/// Class written to test construct and new... patterns
///

///
/// Delete this class when proven a point :)
///
class KLFORTestBP
{
InventTable inventTable;
}

Also note that I added documentation to this method. I will do so for other methods too. When you don’t, you’ll get a BP deviation warning.

2. Parm method
One of the things that are important (or at least I find important), is using parm methods for your class variables. So, let’s create one:

// use parm methods to access class variables
public InventTable parmInventTable(InventTable _inventTable = inventTable)
{
;
inventTable = _inventTable;

return inventTable;
}

3. New method
You should never write code in the new method, or add parameters to it. On the contrary, you should always set this method to protected, and use a static construct() or a static new…() method instead.

// a new method should be protected
// use static new... or construct instead
protected void new()
{
}

4. Run method
The run method will be our method that contains our logic. Here, we print info to the screen

///

/// Executes logic on the parameters of this class
///

///
/// Just for demo purposes
///
public void run()
{
;
info(this.parmInventTable().NameAlias);
}

Note that we are using the parm method instead of directly accessing the variable.

5. Construct method
Because the new method is now protected, we will need a contruct method to be able to create an instance of this class.

private static KLFORTestBP construct()
{
;
return new KLFORTestBP();
}

When a class doesn’t need parameters, you can leave out the ‘private’, but now, it is private because we plan on creating a new…() method that contains parameters. A construct method shouldn’t contain parameters, and should only be used to create a new instance of your class. It is also the only place in your application where you can call the new() method of your class.

6. New…() method
As said earlier, because we need a parameter (an InventTable record), we use a new…() instead of the construct method to create an instance of our class. I will name it newFromInventTable() based on the parameter it has.
In this method, we call the contruct() method to create an instance (instead of new()), set the parm method from the parameter and return the object.

///

/// Creates a new KLFORTestBP object from an InventTable record
///

///
/// The InventTable used to create the object
///
///
/// New instance of KLFORTestBP with the InventTable parameter set
///
///
/// Use a new... method instead of the constuct method because it takes parameters/// A
///
public static KLFORTestBP newFromInventTable(InventTable _inventTable)
{
KLFORTestBP kLFORTestBP;
;

kLFORTestBP = KLFORTestBP::construct();
kLFORTestBP.parmInventTable(_inventTable);

return kLFORTestBP;
}

You could also create an init() method that initializes you class (we don’t need initialization now). The init() method should return a boolean if initialization can go wrong, so you can throw an error.
It would look like this:

public static KLFORTestBP newFromInventTable(InventTable _inventTable)
{
KLFORTestBP kLFORTestBP;
;

kLFORTestBP = KLFORTestBP::construct();
kLFORTestBP.parmInventTable(_inventTable);

if(!kLFORTestBP.init())
{
throw error("Item record has no data"); // todo: create label
}

return kLFORTestBP;
}

Remember to create a label for the text string, or you will get a best practice error.

7. Main method
Now, all we need more is a main method, so this class is runable (by pressing F5 or as a menu item).

server public static void main(Args _args)
{
KLFORTestBP kLFORTestBP;
InventTable inventTable;
;

if(_args && _args.dataset() == tablenum(InventTable))
{
// a button was pressed on a InventTable datasource
inventTable = _args.record();
}
else
{
// for demo, simple select the first one
select firstonly inventTable;
}

// display item information
kLFORTestBP = KLFORTestBP::newFromInventTable(inventTable);
kLFORTestBP.run();
}

Normally, you will get the record from the args object, but for demo purposes, I added the ‘select firstonly’ so you can run the class by pressing F5. As you can see, the new…() method is used to create an instance of the class, and then the run method is called.

There you go, you now have a best practice deviation free class!

8. Using the class
Using the class as a menu item or in code couldn’t be easier.

You can drag/drop the class to the action menu item node in the AOT to create a menu item, and you will be able to use it on any form with the inventTable datasource.

From code, you can simple write this line (assuming there is a variable called inventTable):

KLFORTestBP::newFromInventTable(inventTable).run();

Conclusion:
When writing code that doesn’t contain any best practice deviations (especially when checking them all on compiler level 4), you quickly end up with a lot of methods in your class and wondering if the effort is worth it. It can be a bit painful to get your code best practice deviation free.

However, you’ll also realise that following the best practices has its advantages. Your code will be cleaner, easier to understand, easier to debug because of the parm, constuct and run methods, less subject to change, contain less errors and your class will be used in the way you intended when you wrote it.

More info on MSDN:
Best practices for constructors

Protected new and construct – Part 2

Klaas Deforche — Thu, 18 Feb 2010 17:06:49 +0000

In part 1, we talked about the use of a protected new method and a static constructor, and how it helps improve your classes.

Now let’s see how it helps you maintain you code better when extending classes.

In the previous example, we printed some general information about a record to the screen.
Let’s say that, in case of CustTable we want to have information printed to to screen that is specific to this record, like the AccountNum or Name field.

We will need to create a new class that extends the class we created earlier.

1. ClassDeclaration KLFShowRecordInfo_CustTable
In the ClassDeclaration, we include the keyword ‘extends’ to specify that our new class extends the functionality of the class KLFShowRecordInfo.

class KLFShowRecordInfo_CustTable extends KLFShowRecordInfo
{
}

2. Construct method KLFShowRecordInfo_CustTable
We will also add a construct method to this class. This will create an instance of this class for us, and set the parm method.
Because we extend a class that contains this parm method, we don’t need to add it to this class again.

public static KLFShowRecordInfo_CustTable construct(Common _record)
{
KLFShowRecordInfo_CustTable kLFShowRecordInfo_CustTable;
;

kLFShowRecordInfo_CustTable = new KLFShowRecordInfo_CustTable();
kLFShowRecordInfo_CustTable.parmRecord(_record);

return kLFShowRecordInfo_CustTable;
}

3. Run method KLFShowRecordInfo_CustTable
In the run method, we print data from the CustTable record to screen.

void run()
{
CustTable custTable;
;

custTable = this.parmRecord();

info(custTable.AccountNum);
info(custTable.Name);
}

You could call the super() method if you want the general information to be printed as well.

4. Construct method KLFShowRecordInfo
The only thing we need to change to the existing class is the construct method.
Modify it like this:

public static KLFShowRecordInfo construct(Common _record)
{
KLFShowRecordInfo kLFShowRecordInfo;
;

switch (_record.TableId)
{
case tablenum(CustTable):
kLFShowRecordInfo = KLFShowRecordInfo_CustTable::construct(_record);
break;
default :
kLFShowRecordInfo = new KLFShowRecordInfo();
kLFShowRecordInfo.parmRecord(_record);
break;
}

return kLFShowRecordInfo;
}

The switch will check which table is being processed, and will create an instance of KLFShowRecordInfo_CustTable in case of CustTable. For all other tables, it will construct an instance of KLFShowRecordInfo.

5. TestJob
Let’s test it:

static void KLF_TestRecordInfo(Args _args)
{
CustTable custTable;
VendTable vendTable;
;

select firstonly custTable;
select firstonly vendTable;

// custTable:
KLFShowRecordInfo::construct(custTable).run();
info("----");
// vendTable:
KLFShowRecordInfo::construct(vendTable).run();
}

Output:

00000001
IKEA
—-
VendTable

Conclusion
This concludes my articles about the protected new and construct methods. I realise that the examples are very simple, but the principle will remain the same, even in more complex scenarios.

To sum up:
My basic recommendations when creating classes are:
- Use a protected new method
- Use a construct method
- Use parm methods
- Create a run method that contains your business logic
- Instead of modifying existing classes, create new ones that extend existing

If you disagree, be sure to leave a comment :).

Protected new and construct – Part 1

Klaas Deforche — Mon, 15 Feb 2010 09:16:31 +0000

In this post I want to show you the use of the new() and construct() method when instantiating classes using a simple example class. This is a design that is used a lot an AX.

It is best practice to set the new method as protected (MSDN), and it is also best practice to have a construct method in your class (MSDN). So let’s see how we should implement these best practices.

Like a good recipe, a good class has a few important ingredients:
- Parm methods for variables
- A protected new method
- A static contructor
- A run method

1. ClassDeclaration

As an example, we will create a new class: KLFShowRecordInfo
The function of the class will be to display some information about a record.

class KLFShowRecordInfo
{
Common record;
}

This class has one variable, a record. The type is Common so we can store any record in this variable.

2. Parm method

First thing is to create a parm-method for this variable (created using parmFromCD editorscript):

public Common parmRecord(Common _record = record)
{
;
record = _record;

return record;
}

Your code will be much cleaner and easier to debug when you use parameter methods.

3. New Method

Next, we will override the new method and make it protected:

protected void new()
{
}

Methods that are declared as protected can only be called from methods in the class and in subclasses of the class where the protected method is declared. When we want to create an instance of this class from an other class, we’ll have to call the construct method.
When calling the new() method in any other class, we would get the following compiler error:

The method is declared protected and may only be called from methods in classes derived from KLFShowRecordInfo.

4. Construct method

When using the editorscript to create a construct() method (Right click – Scripts – template – method – construct), it will look like this:

public static KLFShowRecordInfo construct()
{
return new KLFShowRecordInfo();
}

However, I always rewrite it like like this because it is easier to extend afterwards:

public static KLFShowRecordInfo construct()
{
KLFShowRecordInfo kLFShowRecordInfo;
;

kLFShowRecordInfo = new KLFShowRecordInfo();

return kLFShowRecordInfo;
}

Now we’ll have to modify the construct method to receive a parameter, and use the parm method to set the variable in our class:

public static KLFShowRecordInfo construct(Common _record)
{
KLFShowRecordInfo kLFShowRecordInfo;
;

kLFShowRecordInfo = new KLFShowRecordInfo();
kLFShowRecordInfo.parmRecord(_record);

return kLFShowRecordInfo;
}

5. Run method
All we need now is some logic to add to this class. Most of the time, I name the method ‘run’, but you can give it any name you like. The method will display the name of the table of the record you pass to it.

void run()
{
;
info(tableid2name(this.parmRecord().TableId));
}

6. Test job
Next, a job to test it:

static void KLF_TestRecordInfo(Args _args)
{
CustTable custTable;
;

select firstonly custTable;

// this will not work because the new method is protected
// kLFShowRecordInfo = new KLFShowRecordInfo();

KLFShowRecordInfo::construct(custTable).run();
}

You can see that we only need one line of code to call our class, and we don’t need a variable, which makes the code cleaner.

Output:

CustTable

Conclusion
When creating a class, start with declaring the new method as protected. This will force you to use a static construct() method. This in turn will force you to think twice about the structure of your class, and will result in cleaner/better code with a more ‘AX-y’ feel.

In part 2, I will demonstrate how this design principle helps you to maintain your code when extending functionality.