Understanding Partial Execution: Part Two – Execution

In Part One I covered off what happens between server and browser in a partial refresh. Careful thinking about the refresh ID can help minimise the amount of content passed back from the server to the browser. But I emphasised that it has no effect on what happens on the server. In this part I’m going to focus on what gets processed on the server.

First I want to focus on a screenshot of the Events panel from Domino Designer Social Edition.

The area circled in green is what governs the refreshMode and refreshId covered in Part One. The area circled in blue has been in Domino Designer for some time, but most developers have probably never ticked it. That’s because it only handles half of the process. The second half is what’s circled in red and is new in Domino Designer Social Edition. This is a small change (thanks to Tony McGuckin for raising the SPR and Dan O’Connor for adding it), but it’s one that could significantly enhance the performance of your XPages, particularly larger ones. The area in blue corresponds to the execMode property of the eventHandler. The area in red corresponds to the execId.

But what is partial execution mode? To answer that, you need to understand what happens on the server during a partial refresh.

There are a number of steps that the server goes through, which I’ll come back to in my next post. But the short answer is that it retrieves the previous state of the whole XPage. It retrieves which controls were loaded on the XPage – remember that the loaded property cannot be changed by a partial refresh, so what was loaded initially is all that’s available until you do a full refresh. It retrieves what values were previously assigned to the various properties each control. Then it updates that server-side map of the XPage (or component tree) with any changes from the browser and recalculates what it needs to pass back to the browser.

And by default this will be executed over the whole XPage. The server-side process is running in full execution mode.

You’re probably well ahead of me now that I’ve described the server-side process as “full execution mode”, and you hopefully appreciate why I’m so excited about the addition of the area circled in red.

Yes, the checkbox is how to change it from full execution mode to partial execution mode. And the new area allows you to more easily define which ID the server should limit its processing to. In 8.5.3 or lower, you need to go to the Source pane or the Outline view, select the eventHandler, go to All Properties tab and set the execId there – rather fiddly. That’s very important, because if you just set partial execution mode, it only executes over the ID the event is allocated to. Usually that’s not going to be what you want.

Let’s use an example of a panel containing two Combo Boxes, where you want to change the options in the second Combo Box based on the selection in the first. So you set the refresh ID for the whole panel and just set execMode=”partial” on the first Combo Box, forgetting to set the execId. That means the server will limit its processing to the first Combo Box. It will store the value the user entered in the browser, but it won’t do any processing with the second Combo Box. So your options will not change.

Let’s take it a step further and add an Edit Box into the panel. If the user enters a value in the Edit Box, the server will be limiting its processing to the first Combo Box. So in addition, the value entered by the user in the Edit Box will not be stored in the server-side map. That means when the panel is passed back to the browser as the refresh ID, the value entered by the user in the Edit Box will get overwritten!

So if you want to take advantage of partial execution mode, you need to think carefully about the ID you want to use for the server-side execution. And, believe me, you want to take advantage of partial execution mode. In this part I’ve covered what gets processed on the server. In the next part I’ll cover how it gets processed.