Understanding Iterator Binding Refresh Attribute

In this post I am going to focus on the Refresh attribute of an Iterator Binding that we define in the page definition file.

    <executables>
        <iterator Binds="VEmployees" RangeSize="25"
                  DataControl="EmployeesAMDataControl" id="VEmployeesIterator"
                  Refresh="default"/>
    </executables>

The default value is deferred which means that the iterator is going to be executed on demand at the first access. Basically, this option is good enough for most cases and it is recommended to leave it as is and don’t touch. However, it is interesting, at least to me, what other options mean.

Refresh always means that the iterator is going to be refreshed every time whenever the refresh method is invoked on the BindingContainer. So, the iterator is going to be refreshed a number of times within the request during prepare model, update model and render model phases.

ifNeeded gets the iterator refreshed during prepare model and render model phases but only if it has not been refreshed before. For example we have a mater-detail hierarchy and the details are listed first in the page definition. This will cause  the master to be refreshed twice once for the details and once for its own iterator. IfNeeded option could help here to avoid double refreshes.

The rest of the options are self-explaining.
Never means that the framework will never refresh the iterator, but you can do that manually in your Java code.
PrepareModel forces the iterator to be refreshed each time during the prepare model phase, but PrepareModelIfNeeded does it only if the iterator has not been refreshed to this point. The same is about renderModel and renderModelIfNeeded at the Render Model phase.

So, the refresh attribute determines the lifecycle phases in which to refresh the iterator. Besides that we can provide an optional boolean condition in order to control whether the iterator is really going to be refreshed. We can do that by specifiyng an EL in the RefreshCondition attribute. Whenever the framework is about to refresh the iterator it evaluates that EL expression and if it returns false the iterator is going to be skipped.


That's it!