| <!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>Create a configuration instance - 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="Create a configuration instance"> |
| <meta property="og:locale" content="en_US"> |
| <meta property="og:url" content="https://freemarker.apache.org/docs/pgui_quickstart_createconfiguration.html"> |
| <link rel="canonical" href="https://freemarker.apache.org/docs/pgui_quickstart_createconfiguration.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="pgui.html"><span itemprop="name">Programmer's Guide</span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_quickstart.html"><span itemprop="name">Getting Started</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="pgui_quickstart_createconfiguration.html"><span itemprop="name">Create a configuration instance</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","Programmer\'s Guide","Getting Started","Create a configuration instance"];</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="pgui_quickstart.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_quickstart_createdatamodel.html"><span>Next</span></a></div><div class="title-wrapper"> |
| <h1 class="content-header header-section1" id="pgui_quickstart_createconfiguration" itemprop="headline">Create a configuration instance</h1> |
| </div></div><p>First you have to create a |
| <code class="inline-code">freemarker.template.Configuration</code> instance and |
| adjust its settings. A <code class="inline-code">Configuration</code> instance is |
| the central place to store the application level settings of |
| FreeMarker. Also, it deals with the creation and |
| <em>caching</em> of pre-parsed templates (i.e., |
| <code class="inline-code">Template</code> objects).</p><p>Normally you will <em>do this only once</em> at the |
| beginning of the application (possibly servlet) life-cycle:</p> |
| |
| <div class="code-block role-unspecified"> |
| <pre class="code-block-body">// Create your Configuration instance, and specify if up to what FreeMarker |
| // version (here 2.3.32) do you want to apply the fixes that are not 100% |
| // backward-compatible. See the Configuration JavaDoc for details. |
| Configuration cfg = new Configuration(Configuration.VERSION_2_3_32); |
| |
| // Specify the source where the template files come from. Here I set a |
| // plain directory for it, but non-file-system sources are possible too: |
| cfg.setDirectoryForTemplateLoading(new File("<em>/where/you/store/templates</em>")); |
| |
| // From here we will set the settings recommended for new projects. These |
| // aren't the defaults for backward compatibilty. |
| |
| // Set the preferred charset template files are stored in. UTF-8 is |
| // a good choice in most applications: |
| cfg.setDefaultEncoding("UTF-8"); |
| |
| // Sets how errors will appear. |
| // During web page *development* TemplateExceptionHandler.HTML_DEBUG_HANDLER is better. |
| cfg.setTemplateExceptionHandler(TemplateExceptionHandler.RETHROW_HANDLER); |
| |
| // Don't log exceptions inside FreeMarker that it will thrown at you anyway: |
| cfg.setLogTemplateExceptions(false); |
| |
| // Wrap unchecked exceptions thrown during template processing into TemplateException-s: |
| cfg.setWrapUncheckedExceptions(true); |
| |
| // Do not fall back to higher scopes when reading a null loop variable: |
| cfg.setFallbackOnNullLoopVariable(false); |
| |
| // To accomodate to how JDBC returns values; see Javadoc! |
| cfg.setSQLDateAndTimeTimeZone(TimeZone.getDefault());</pre> </div> |
| <p>From now you should use this <em>single</em> |
| configuration instance (i.e., its a singleton). Note however that if a |
| system has multiple independent components that use FreeMarker, then |
| of course they will use their own private |
| <code class="inline-code">Configuration</code> instances.</p> <div class="callout warning"> |
| <strong class="callout-label">Warning!</strong> |
| |
| <p>Do not needlessly re-create <code class="inline-code">Configuration</code> |
| instances; it's expensive, among others because you lose the |
| template cache. <code class="inline-code">Configuration</code> instances meant to |
| be application-level singletons.</p> |
| </div> |
| <p>In multi-threaded applications (like Web sites) the settings in |
| the <code class="inline-code">Configuration</code> instance must not be modified |
| anymore after this point. Thus it can be treated as "effectively |
| immutable" object, so you can continue with <em>safe |
| publishing</em> techniques (see JSR 133 and related literature) |
| to make the instance available for other threads. Like, publish the |
| instance through a final or volatile filed, or through a thread-safe |
| IoC container (like the one provided by Spring). |
| <code class="inline-code">Configuration</code> methods that don't deal with |
| modifying settings are thread-safe.</p><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_quickstart.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_quickstart_createdatamodel.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> |
