| <!doctype html> |
| <!-- Generated by FreeMarker/Docgen from DocBook --> |
| <html lang="en" class="page-type-section"> |
| <head prefix="og: http://ogp.me/ns#"> |
| <meta charset="utf-8"> |
| <title>attempt, recover - Apache FreeMarker Manual</title> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <meta name="format-detection" content="telephone=no"> |
| <meta property="og:site_name" content="Apache FreeMarker Manual"> |
| <meta property="og:title" content="attempt, recover"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/ref_directive_attempt.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/ref_directive_attempt.html"> |
| <link rel="icon" href="favicon.png" type="image/png"> |
| <link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Roboto:500,700,400,300|Droid+Sans+Mono"> |
| <link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css?1707770044859"> |
| <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/cookie-bar/cookiebar-latest.min.js"></script> |
| </head> |
| <body itemscope itemtype="https://schema.org/Code"> |
| <meta itemprop="url" content="https://freemarker.apache.org/docs/"> |
| <meta itemprop="name" content="Apache FreeMarker Manual"> |
| |
| <!--[if lte IE 9]> |
| <div class="oldBrowserWarning" style="display: block"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <![endif]--> <div class="oldBrowserWarning"> |
| Unsupported web browser - Use a modern browser to view this website! |
| </div> |
| <div class="header-top-bg"><div class="site-width header-top"><div id="hamburger-menu" role="button"></div> <div class="logo"> |
| <a href="https://freemarker.apache.org" role="banner"><img itemprop="image" src="logo.png" alt="FreeMarker"></a> </div> |
| <ul class="tabs"><li><a href="https://freemarker.apache.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="https://freemarker.apache.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/projects/FREEMARKER" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="https://freemarker.apache.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="index.html" class="navigation-header">Manual</a><div class="navigation-header"></div><form method="get" class="search-form" action="search-results.html"><fieldset><legend class="sr-only">Search form</legend><label for="search-field" class="sr-only">Search query</label><input id="search-field" name="q" type="search" class="search-input" placeholder="Search" spellcheck="false" autocorrect="off" autocomplete="off"><button type="submit" class="search-btn"><span class="sr-only">Search</span></button></fieldset></form></div><div class="site-width breadcrumb-row"> <div class="breadcrumbs"> |
| <ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="index.html"><span itemprop="name">Apache FreeMarker Manual</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref.html"><span itemprop="name">Template Language Reference</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directives.html"><span itemprop="name">Directive Reference</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directive_attempt.html"><span itemprop="name">attempt, recover</span></a></li></ul> </div> |
| <div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div> <div class="main-content site-width"> |
| <div class="content-wrapper"> |
| <div id="table-of-contents-wrapper" class="col-left"> |
| <script>var breadcrumb = ["Apache FreeMarker Manual","Template Language Reference","Directive Reference","attempt, recover"];</script> |
| <script src="toc.js?1707770044859"></script> |
| <script src="docgen-resources/main.min.js?1707770044859"></script> |
| </div> |
| <div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="ref_directive_assign.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_autoesc.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="ref_directive_attempt" itemprop="headline">attempt, recover</h1> |
| </div></div><div class="page-menu"> |
| <div class="page-menu-title">Page Contents</div> |
| <ul><li><a class="page-menu-link" href="#autoid_80" data-menu-target="autoid_80">Synopsis</a></li><li><a class="page-menu-link" href="#autoid_81" data-menu-target="autoid_81">Description</a></li></ul> </div><a name="ref.directive.attempt"></a> |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_80">Synopsis</h2> |
| |
| |
| |
| <pre class="metaTemplate"> |
| <code class="inline-code"><#attempt> |
| <em class="code-color">attempt block</em> |
| <#recover> |
| <em class="code-color">recover block</em> |
| </#attempt> |
| </code> |
| </pre> |
| |
| |
| <p>Where:</p> |
| |
| <ul> |
| <li> |
| <code class="inline-code"><em class="code-color">attempt |
| block</em></code>: 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 |
| <code class="inline-code"><em class="code-color">recover block</em></code> will |
| be executed. |
| </li> |
| |
| <li> |
| <code class="inline-code"><em class="code-color">recover |
| block</em></code>: Template block with any content. |
| This will be executed only if there was an error during the |
| execution of the <code class="inline-code"><em class="code-color">attempt |
| block</em></code>. You may print an error messages |
| here and such. |
| </li> |
| </ul> |
| |
| <p>The <code class="inline-code"><em class="code-color">recover</em></code> is |
| mandatory. <code class="inline-code">attempt</code>/<code class="inline-code">recover</code> can |
| be nested freely into other <code class="inline-code"><em class="code-color">attempt |
| block</em></code>s or <code class="inline-code"><em class="code-color">recover |
| block</em></code>s.</p> |
| |
| <div class="callout note"> |
| <strong class="callout-label">Note:</strong> |
| |
| <p>The format shown here is supported starting from 2.3.3; |
| earlier it was |
| <code class="inline-code"><#attempt><em class="code-color">...</em><#recover><em class="code-color">...</em></#recover></code>, |
| 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.</p> |
| </div> |
| |
| |
| |
| |
| |
| |
| <h2 class="content-header header-section2" id="autoid_81">Description</h2> |
| |
| |
| <p>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 |
| <code class="inline-code"><em class="code-color">attempt block</em></code>, then |
| the output of the <code class="inline-code"><em class="code-color">attempt |
| block</em></code> is rolled back <span class="marked-for-programmers">(and the error is logged, with the default |
| configuration at least)</span>, and the |
| <code class="inline-code"><em class="code-color">recover block</em></code> is |
| executed instead, then template execution continues normally after |
| the <code class="inline-code"><em class="code-color">recover block</em></code>. If |
| no error occurs during the execution of the |
| <code class="inline-code"><em class="code-color">attempt block</em></code>, then |
| the <code class="inline-code"><em class="code-color">recover block</em></code> is |
| ignored. A simple example:</p> |
| |
| |
| |
| <div class="code-block role-template"> |
| <div class="code-block-label">Template</div><pre class="code-block-body">Primary content |
| <#attempt> |
| Optional content: ${thisMayFails} |
| <#recover> |
| Ops! The optional content is not available. |
| </#attempt> |
| Primary content continued</pre> </div> |
| |
| |
| <p>If the <code class="inline-code">thisMayFails</code> variable doesn't exist |
| (or any other error occurs at that place), then the output |
| is:</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">Primary content |
| Ops! The optional content is not available. |
| Primary content continued</pre> </div> |
| |
| |
| <p>If the <code class="inline-code">thisMayFails</code> variable exists and |
| it's value is <code class="inline-code">123</code>, then the output is:</p> |
| |
| |
| |
| <div class="code-block role-output"> |
| <div class="code-block-label">Output</div><pre class="code-block-body">Primary content |
| Optional content: 123 |
| Primary content continued</pre> </div> |
| |
| |
| <p>The <code class="inline-code"><em class="code-color">attempt |
| block</em></code> has an all-or-none semantic: either |
| the entire content of the <code class="inline-code"><em class="code-color">attempt |
| block</em></code> is output (when there was no error), |
| or no output at all results from the execution of the |
| <code class="inline-code"><em class="code-color">attempt block</em></code> (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!". (<span class="marked-for-programmers">This is implemented with the aggressive |
| buffering of the output inside the <code class="inline-code"><em class="code-color">attempt |
| block</em></code>. Not even the <code class="inline-code">flush</code> |
| directive will send the output to the client.</span>)</p> |
| |
| <p>To prevent misunderstandings coming from the above example: |
| <code class="inline-code">attempt</code>/<code class="inline-code">recover</code> is not (only) |
| for handling undefined variables (for that use <a href="dgui_template_exp.html#dgui_template_exp_missing">missing value handler |
| operators</a>). It can handle all kind of errors that occurs when |
| the block is executed (i.e. not syntactical errors, which are |
| detected earlier). It 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 database server outage). So |
| you put the whole advertisement printing into an |
| <code class="inline-code"><em class="code-color">attempt block</em></code>.</p> |
| |
| <p>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 (<span class="marked-for-programmers">see more <a href="pgui_config_errorhandling.html">here...</a></span>). The |
| <code class="inline-code">attempt</code> directive doesn't consider such |
| suppressed errors as errors.</p> |
| |
| <p>Inside a <code class="inline-code"><em class="code-color">recover |
| block</em></code> the error message of the error is |
| available with the <code class="inline-code">error</code> <a href="ref_specvar.html">special variable</a>. Don't forget that |
| references to special variable are started with dot (for example: |
| <code class="inline-code">${.error}</code>).</p> |
| |
| <p><span class="marked-for-programmers">By default errors occurring |
| inside an <code class="inline-code"><em class="code-color">attempt |
| block</em></code> are <a href="pgui_misc_logging.html">logged</a> with |
| <code class="inline-code">ERROR</code> level, despite that the template recovers |
| from them. This is because <code class="inline-code">attempt</code> is not meant |
| to be a general purpose error handler mechanism, like |
| <code class="inline-code">try</code> is in Java. It's for decreasing the impact of |
| unexpected errors on the visitors, by making it possible that only |
| part of the page is going down, instead of the whole page. But it's |
| still an error, something that needs the attention of the operators. |
| (The way this error is reported can be customized with the |
| <code class="inline-code">attempt_exception_reporter</code> configuration setting, |
| since FreeMarker 2.3.27.)</span></p> |
| <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_directive_assign.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_autoesc.html"><span>Next</span></a></div></div></div></div> </div> |
| </div> |
| <div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="https://freemarker.apache.org/">What is FreeMarker?</a></li><li><a href="https://freemarker.apache.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="app_faq.html">FAQ</a></li><li><a itemprop="license" href="app_license.html">License</a></li><li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy policy</a></li></ul></div><div class="column"><h3 class="column-header">Often used / Reference</h3><ul><li><a href="https://try.freemarker.apache.org/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li><li><a href="api/freemarker/core/Configurable.html#setSetting-java.lang.String-java.lang.String-">Configuration settings</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/apache/freemarker">Github project page</a></li><li><a href="https://issues.apache.org/jira/projects/FREEMARKER">Report a bug</a></li><li><a href="https://freemarker.apache.org/report-security-vulnerabilities.html">Report security vulnerability</a></li><li><a href="https://stackoverflow.com/questions/ask?tags=freemarker">Get help on StackOverflow</a></li><li><a href="https://twitter.com/freemarker">Announcements on Twitter</a></li><li><a href="https://freemarker.apache.org/mailing-lists.html">Discuss on mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/apache/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="https://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"> <p class="last-generated"> |
| Last generated: |
| <time itemprop="dateModified" datetime="2024-02-12T20:34:04Z" title="Monday, February 12, 2024 at 8:34:04 PM Greenwich Mean Time">2024-02-12 20:34:04 GMT</time>, for Freemarker 2.3.32 </p> |
| <p class="copyright"> |
| © <span itemprop="copyrightYear">1999</span>–2024 |
| <a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="https://apache.org/">The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. </p> |
| </div></div></div></body> |
| </html> |
