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 therecover 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 theattempt block
. You may print an error messages here and such.
The recover
is
mandatory. attempt
/recover
can
be nested freely into other attempt
block
s or recover
block
s.
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:
Primary content <#attempt> Optional content: ${thisMayFails} <#recover> Ops! The optional content is not available. </#attempt> Primary content continued
If the thisMayFails
variable doesn't exist,
then the output is:
Primary content Ops! The optional content is not available. Primary content continued
If the thisMayFails
variable exists and
it's value is 123
, then the output is:
Primary content Optional content: 123 Primary content continued
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
.