attempt, recover
Page Contents
Synopsis
<#attempt> attempt block <#recover> recover block </#attempt>
Where:
- attempt block: Template block with any content. This will be always executed, but if an error occurs during that, all output from this block is rolled back, and the recover block will be executed.
- recover block: Template block with any content. This will be executed only if there was an error during the execution of the attempt block. You may print an error messages here and such.
The recover is mandatory. attempt/recover can be nested freely into other attempt blocks or recover blocks.
Note
The format shown here is supported starting from 2.3.3; earlier it was <#attempt>...<#recover>...</#recover>, which is still supported for backward compatibility. Furthermore, these directives were introduced with FreeMarker 2.3.1, so they aren't exist in 2.3.
Description
These directives are used if you want the page successfully outputted even if the outputting of a certain part of the page fails. If an error occurs during the execution of the attempt block, then the template execution is not aborted, but the recover block is executed instead of the attempt block. If no error occurs during the execution of the attempt block, then the recover block is ignored. A simple example:
 | | | |
|
| | |
| | |
If the thisMayFails variable doesn't exist, then the output is:
| | | |
|
| | |
| | |
If the thisMayFails variable exists and it's value is 123, then the output is:
| | | |
|
| | |
| | |
The attempt block has an all-or-none semantic: either the entire content of the attempt block is output (when there was no error), or no output at all results from the execution of the attempt block (when there was an error). For example, above, the failure happens after ``Optional content: '' was printed, still it is not there in the output before the ``Ops!''. (This is implemented with the aggressive buffering of the output inside the attempt block. Not even the flush directive will send the output to the client.)
To prevent misunderstandings coming from the above example: attempt/recover is not (only) for handling undefined variables (for that use missing value handler operators). It can handle all kind of errors that occurs when the block is executed (i.e. not syntactical errors, which are detected earlier). And it's meant to enclose bigger template fragments, where error can occur at various points. For example, you have a part in your template that deals with printing advertisements, but that's not the primary content of the page, so you don't want your whole page be down just because some error occurs with the printing of the advertisements (say, because of a temporal database server faliure). So you put the whole advertisement printing into an attempt block.
In some environments programmers configure FreeMarker so that it doesn't abort template execution for certain errors, but continues execution, possibly after printing some error indicator to the output (see more here...). The attempt directive doesn't consider such suppressed errors as errors.
Inside a recover block the error message of the error is available with the error special variable. Don't forget that references to special variable are started with dot (for example: ${.error}).
Errors occurring during template execution are always logged, even if they occur inside an attempt block.
