http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/pgui_misc_charset.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/pgui_misc_charset.html b/builds/2.3.26-nightly/pgui_misc_charset.html new file mode 100644 index 0000000..1958707 --- /dev/null +++ b/builds/2.3.26-nightly/pgui_misc_charset.html @@ -0,0 +1,172 @@ +<!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>Charset issues - 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="Charset issues"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/pgui_misc_charset.html";> +<link rel="canonical" href="http://freemarker.org/docs/pgui_misc_charset.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://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?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache FreeMarker Manual"> + + <!--[if lte IE 9]> + <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div> + <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.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="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.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="searc h-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"><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_misc.html"><span itemprop="name">Miscellaneous</span></a></li><li class="step-3" itemprop="it emListElement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="pgui_misc_charset.html"><span itemprop="name">Charset issues</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><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","Miscellaneous","Charset issues"];</script> + <script src="toc.js?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></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_misc_var.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_multithreading.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="pgui_misc_charset" itemprop="headline">Charset issues</h1> +</div></div><div class="page-menu"> +<div class="page-menu-title">Page Contents</div> +<ul><li><a class="page-menu-link" href="#autoid_52" data-menu-target="autoid_52">The charset of the input</a></li><li><a class="page-menu-link" href="#autoid_53" data-menu-target="autoid_53">The charset of the output</a></li></ul> </div><p>FreeMarker, as most Java applications, works with "<a href="gloss.html#gloss.unicode">UNICODE</a> text" (UTF-16). Nonetheless, + there are situations when it must deal with <a href="gloss.html#gloss.charset">charsets</a>, because it has to exchange + data with the outer world that may uses various other charsets.</p> + + + + +<h2 class="content-header header-section2" id="autoid_52">The charset of the input</h2> + + + <p>When FreeMarker has to load a template file (or an unparsed + text file), then it must know the charset of the file, since files + are just raw byte sequences. You can use the + <code class="inline-code">encoding</code> <a href="pgui_config_settings.html">setting</a> to specify the + charset. This setting takes effect only when FreeMarker loads a + template (parsed or unparsed) with the + <code class="inline-code">getTemplate</code> method of + <code class="inline-code">Configuration</code>. Note that the <a href="ref_directive_include.html#ref.directive.include"><code>include</code> + directive</a> uses this method internally, so the value of the + <code class="inline-code">encoding</code> setting is significant for an already + loaded template if the template contains <code class="inline-code">include</code> + directive call.</p> + + <p>The getter and setter method of the + <code class="inline-code">encoding</code> setting is special in the first + (configuration) layer. The getter method guesses the return value + based on a <code class="inline-code">Locale</code> passed as parameter; it looks + up the encoding in a table that maps locales to encodings (called + encoding map), and if the locale was not found there, it returns the + default encoding. You can fill the encoding map with the + <code class="inline-code">setEncoding(Locale locale, String encoding)</code> + method of the configuration; the encoding map is initially empty. + The default encoding is initially the value of the + <code class="inline-code">file.encoding</code> system property, but you always + should set a default default with the + <code class="inline-code">setDefaultEncoding</code> method, rather than relying on + that. For new projects, a popular default encoding is + <code class="inline-code">utf-8</code>.</p> + + <p>You can give the charset directly by overriding the + <code class="inline-code">encoding</code> setting in the template layer or runtime + environment layer (When you specify an encoding as the parameter of + <code class="inline-code">getTemplate</code> method, you override the + <code class="inline-code">encoding</code> setting in the template layer.). If you + don't override it, the effective value will be what the + <code class="inline-code">configuration.getEncoding(Locale)</code> method returns + for the effective value of the <code class="inline-code">locale</code> + setting.</p> + + <p>Also, instead of relying on this charset guessing mechanism, + you can specify the charset of the template in the template file + itself, with the <a href="ref_directive_ftl.html#ref.directive.ftl"><a href="ref_directive_ftl.html#ref.directive.ftl"><code>ftl</code></a> + directive</a>, like <code class="inline-code"><#ftl + encoding="utf-8"></code>.</p> + + <p>Note that the charset of the template is independent from the + charset of the output that the tempalte generates (unless the + enclosing software deliberately sets the output charset to the same + as the template charset).</p> + + + + + +<h2 class="content-header header-section2" id="autoid_53">The charset of the output</h2> + + + <div class="callout note"> + <strong class="callout-label">Note:</strong> + + <p>The <code class="inline-code">output_encoding</code> setting/variable and + the <a href="ref_builtins_string.html#ref_builtin_url"><code>url</code> + built-in</a> is available since FreeMarker 2.3.1. It doesn't + exist in 2.3.</p> + </div> + + + <p>In principle FreeMarker does not deal with the charset + of the output, since it writes the output to a + <code class="inline-code">java.io.Writer</code>. Since the + <code class="inline-code">Writer</code> is made by the software that encapsulates + FreeMarker (such as a Web application framework), the output charset + is controlled by the encapsulating software. Still, FreeMarker has a + setting called <code class="inline-code">output_encoding</code> (starting from + FreeMarker version 2.3.1). The enclosing software should set this + setting (to the charset that the <code class="inline-code">Writer</code> uses), to + inform FreeMarker what charset is used for the output (otherwise + FreeMarker can't find it out). Some features, such as the <a href="ref_builtins_string.html#ref_builtin_url"><code>url</code> built-in</a>, + and the <a href="ref_specvar.html"><code>output_encoding</code> special + variable</a> utilize this information. Thus, if the enclosing + software doesn't set this setting then FreeMarker features that need + to know the output charset can't be used.</p> + + <p>If you write software that will use FreeMarker, you may wonder + what output charset should you choose. Of course it depends on the + consumer of the FreeMarker output, but if the consumer is flexible + regarding this question, then the common practice is either using + the charset of the template file for the output, or using UTF-8. + Using UTF-8 is usually a better practice, because arbitrary text may + comes from the data-model, which then possibly contains characters + that couldn't be encoded with the charset of the template.</p> + + <p>FreeMarker settings can be set for each individual template + processing if you use + <code class="inline-code">Template.createProcessingEnvironment(<em class="code-color">...</em>)</code> + plus + <code class="inline-code">Environment.process(<em class="code-color">...</em>)</code> + instead of + <code class="inline-code">Template.process(<em class="code-color">...</em>)</code>. + Thus, you can set the <code class="inline-code">output_encoding</code> setting for + each template execution independently:</p> + + + +<div class="code-wrapper"><pre class="code-block code-unspecified">Writer w = new OutputStreamWriter(out, outputCharset); +Environment env = template.createProcessingEnvironment(dataModel, w); +env.setOutputEncoding(outputCharset); +env.process();</pre></div> + <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_misc_var.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_multithreading.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="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>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></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://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="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html>
http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/pgui_misc_jythonwrapper.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/pgui_misc_jythonwrapper.html b/builds/2.3.26-nightly/pgui_misc_jythonwrapper.html new file mode 100644 index 0000000..b29ad5b --- /dev/null +++ b/builds/2.3.26-nightly/pgui_misc_jythonwrapper.html @@ -0,0 +1,133 @@ +<!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>Jython wrapper - 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="Jython wrapper"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/pgui_misc_jythonwrapper.html";> +<link rel="canonical" href="http://freemarker.org/docs/pgui_misc_jythonwrapper.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://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?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache FreeMarker Manual"> + + <!--[if lte IE 9]> + <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div> + <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.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="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.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="searc h-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"><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_misc.html"><span itemprop="name">Miscellaneous</span></a></li><li class="step-3" itemprop="it emListElement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="pgui_misc_jythonwrapper.html"><span itemprop="name">Jython wrapper</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><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","Miscellaneous","Jython wrapper"];</script> + <script src="toc.js?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></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_misc_ant.html"><span>Previous</span></a><a class="paging-arrow next" href="ref.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="pgui_misc_jythonwrapper" itemprop="headline">Jython wrapper</h1> +</div></div><div class="page-menu"> +<div class="page-menu-title">Page Contents</div> +<ul><li><a class="page-menu-link" href="#autoid_71" data-menu-target="autoid_71">TemplateHashModel functionality</a></li><li><a class="page-menu-link" href="#autoid_72" data-menu-target="autoid_72">TemplateScalarModel functionality</a></li><li><a class="page-menu-link" href="#autoid_73" data-menu-target="autoid_73">TemplateBooleanModel functionality</a></li><li><a class="page-menu-link" href="#autoid_74" data-menu-target="autoid_74">TemplateNumberModel functionality</a></li><li><a class="page-menu-link" href="#autoid_75" data-menu-target="autoid_75">TemplateSequenceModel functionality</a></li></ul> </div><p>The <code class="inline-code">freemarker.ext.jython</code> package consists of + models that enable any Jython object to be used as a + <code class="inline-code">TemplateModel</code>. In the very basic case, you only + need to call the</p> + +<div class="code-wrapper"><pre class="code-block code-unspecified">public TemplateModel wrap(Object obj);</pre></div><p>method of the + <code class="inline-code">freemarker.ext.jython.JythonWrapper</code> class. This + method will wrap the passed object into an appropriate + <code class="inline-code">TemplateModel</code>. Below is a summary of the properties + of returned model wrappers. Let's assume that the model that resulted + from the <code class="inline-code">JythonWrapper</code> call on object + <code class="inline-code">obj</code> is named <code class="inline-code">model</code> in the + template model root for the sake of the following discussion.</p> + + + + +<h2 class="content-header header-section2" id="autoid_71">TemplateHashModel functionality</h2> + + + <p><code class="inline-code">PyDictionary</code> and + <code class="inline-code">PyStringMap</code> will be wrapped into a hash model. + Key lookups are mapped to the <code class="inline-code">__finditem__</code> + method; if an item is not found, a model for <code class="inline-code">None</code> + is returned.</p> + + + + + +<h2 class="content-header header-section2" id="autoid_72">TemplateScalarModel functionality</h2> + + + <p>Every python object will implement + <code class="inline-code">TemplateScalarModel</code> whose + <code class="inline-code">getAsString()</code> method simply delegates to + <code class="inline-code">toString()</code>.</p> + + + + + +<h2 class="content-header header-section2" id="autoid_73">TemplateBooleanModel functionality</h2> + + + <p>Every python object will implement + <code class="inline-code">TemplateBooleanModel</code> whose + <code class="inline-code">getAsBoolean()</code> method simply delegates to + <code class="inline-code">__nonzero__()</code> in accordance with Python semantics + of true/false.</p> + + + + + +<h2 class="content-header header-section2" id="autoid_74">TemplateNumberModel functionality</h2> + + + <p>Model wrappers for <code class="inline-code">PyInteger</code>, + <code class="inline-code">PyLong</code>, and <code class="inline-code">PyFloat</code> objects + implement <code class="inline-code">TemplateNumberModel</code> whose + <code class="inline-code">getAsNumber()</code> method returns + <code class="inline-code">__tojava__(java.lang.Number.class)</code>.</p> + + + + + +<h2 class="content-header header-section2" id="autoid_75">TemplateSequenceModel functionality</h2> + + + <p>Model wrappers for all classes that extend + <code class="inline-code">PySequence</code> will implement + <code class="inline-code">TemplateSequenceModel</code> and thus their elements + will be accessible by index using the <code class="inline-code">model[i]</code> + syntax, which will delegate to <code class="inline-code">__finditem__(i)</code>. + You can also query the length of the array or the size of the list + using the <code class="inline-code">model?size</code> built-in, which will + delegate to <code class="inline-code">__len__()</code>.</p> + <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_misc_ant.html"><span>Previous</span></a><a class="paging-arrow next" href="ref.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="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>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></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://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="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/pgui_misc_logging.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/pgui_misc_logging.html b/builds/2.3.26-nightly/pgui_misc_logging.html new file mode 100644 index 0000000..6a0fce1 --- /dev/null +++ b/builds/2.3.26-nightly/pgui_misc_logging.html @@ -0,0 +1,239 @@ +<!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>Logging - 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="Logging"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/pgui_misc_logging.html";> +<link rel="canonical" href="http://freemarker.org/docs/pgui_misc_logging.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://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?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache FreeMarker Manual"> + + <!--[if lte IE 9]> + <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div> + <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.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="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.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="searc h-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"><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_misc.html"><span itemprop="name">Miscellaneous</span></a></li><li class="step-3" itemprop="it emListElement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="pgui_misc_logging.html"><span itemprop="name">Logging</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><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","Miscellaneous","Logging"];</script> + <script src="toc.js?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></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_misc_beanwrapper.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_servlet.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="pgui_misc_logging" itemprop="headline">Logging</h1> +</div></div><div class="page-menu"> +<div class="page-menu-title">Page Contents</div> +<ul><li><a class="page-menu-link" href="#autoid_61" data-menu-target="autoid_61">Logging library selection</a></li><li><a class="page-menu-link" href="#autoid_62" data-menu-target="autoid_62">Logging categories</a></li></ul> </div> + + + + +<h2 class="content-header header-section2" id="autoid_61">Logging library selection</h2> + + + <p>Is short, the recommended setup in contemporary application + (as of 2015) is using SLF4J API for logging everywhere. To get + FreeMarker 2.3.x. to use SLF4J, simply add the + <code class="inline-code">org.slf4j:log4j-over-slf4j</code> dependency to your + project, and ensure that <code class="inline-code">log4j:log4j</code> isn't + present. (Starting from FreeMarker 2.4.x you don't need + <code class="inline-code">log4j-over-slf4j</code> anymore, though it does no harm + either.)</p> + + <p>Read on if you are curious about the details, or if you can't + use SLF4J...</p> + + <p>FreeMarker integrates with the following logging libraries: + <a href="http://www.slf4j.org/";>SLF4J</a>, <a href="http://commons.apache.org/logging/";>Apache Commons + Logging</a>, <a href="http://jakarta.apache.org/log4j";>Log4J</a> 1.x, <a href="http://jakarta.apache.org/avalon/logkit";>Avalon + LogKit</a>, and <a href="http://java.sun.com/j2se/1.4/docs/api/java/util/logging/package-summary.html";><code>java.util.logging</code></a>. + By default, FreeMarker will look for the these logging libraries in + the following order, and will automatically use the first one it + finds (in 2.3.x): Log4J (will use SLF4J instead if it's a + properly installed <code class="inline-code">log4j-over-slf4j</code>, since + 2.3.22), Apache Avalon LogKit, <code class="inline-code">java.util.logging</code>. + As you can see, Log4j has the highest priority. The presence of + Log4j is simply detected from the presence of the + <code class="inline-code">org.apache.log4j.Logger</code> class, which means that + Log4j redirections like <code class="inline-code">log4j-over-slf4j</code> or + <code class="inline-code">log4j-1.2-api</code> will also get the highest + priority.</p> + + <p>Prior to FreeMarker 2.4, SLF4J and Apache Commons Logging + aren't searched automatically due to backward compatibility + constraints. But if you have + <code class="inline-code">org.slf4j:log4j-over-slf4j</code> properly installed + (means, you have no real Log4j in your class path, and SLF4J has a + backing implementation like <code class="inline-code">logback-classic</code>), + then FreeMarker will use the SLF4J API directly instead of the Log4j + API (since FreeMarker 2.3.22).</p> + + <p>Note that a similar trick can be applied for logging into + Log4j2: If <code class="inline-code">org.apache.logging.log4j:log4j-1.2-api</code> + is present, FreeMarker 2.3.x will pick that as it looks like Log4j, + but all the messages will actually go to Log4j2.</p> + + <p>If the auto detection doesn't give you the result that you + want, you can set the + <code class="inline-code">org.freemarker.loggerLibrary</code> system property to + select a logger library explicitly (since 2.3.22), like:</p> + + + +<div class="code-wrapper"><pre class="code-block code-unspecified">java <em>...</em> -Dorg.freemarker.loggerLibrary=SLF4J</pre></div> + + <p>The supported system property values are: + <code class="inline-code">SLF4J</code>, <code class="inline-code">CommonsLogging</code>, + <code class="inline-code">JUL</code> (for <code class="inline-code">java.util.logging</code>), + <code class="inline-code">Avalon</code>, <code class="inline-code">auto</code> (the default + behavior), <code class="inline-code">none</code> (disables logging).</p> + + <p>Note that for reliable operation, the system property should + be set when the JVM starts (like above), not later from Java + code.</p> + + <p>Using SLF4J is recommended, as it works best with FreeMarker, + and also because it will be the highest priority auto detected + logger starting from FreeMarker 2.4.</p> + + + + + +<h2 class="content-header header-section2" id="autoid_62">Logging categories</h2> + + + <p>All log messages produced by FreeMarker are logged with a + logger category that starts with <code class="inline-code">freemarker.</code>. The + currently used logger categories are:</p> + + <div class="table-responsive"> + <table class="table"> + + <thead> + <tr> + <th>Log category name</th> + + + <th>Purpose</th> + + </tr> + + </thead> + + + <tbody> + <tr> + <td><code class="inline-code">freemarker.beans</code></td> + + + <td>Logs messages of the Beans wrapper module.</td> + + </tr> + + + <tr> + <td><code class="inline-code">freemarker.cache</code></td> + + + <td>Logs messages related to template loading and + caching.</td> + + </tr> + + + <tr> + <td><code class="inline-code">freemarker.runtime</code></td> + + + <td>Logs messages related to template execution that doesn't + fit any of the more specific categories. Most importantly, it + logs template exceptions thrown during template processing + (however that should be disabled in modern application; see + later).</td> + + </tr> + + + <tr> + <td><code class="inline-code">freemarker.runtime.attempt</code></td> + + + <td>Logs template exceptions thrown during template processing + and caught by + <code class="inline-code">attempt</code>/<code class="inline-code">recover</code> + directives, with DEBUG severity. Note that such exceptions + will be still also logged with their normal logger (like + <code class="inline-code">freemarker.runtime</code>).</td> + + </tr> + + + <tr> + <td><code class="inline-code">freemarker.servlet</code></td> + + + <td>Logs messages of the <code class="inline-code">FreemarkerServlet</code> + class.</td> + + </tr> + + + <tr> + <td><code class="inline-code">freemarker.jsp</code></td> + + + <td>Logs messages of the FreeMarker JSP support.</td> + + </tr> + + </tbody> + + </table> + </div> + + + <p>One quirk relating this is that FreeMarker will log exceptions + during template execution under the + <code class="inline-code">freemarker.runtime</code> category even if the exception + continues propagating and so eventually will be thrown by + <code class="inline-code">Template.process</code> or + <code class="inline-code">Environment.process</code> anyway. (Those are the API + calls with which the template was invoked from the application or + the application framework.) Well behaving applications log the + exceptions thrown at them, or rarely, handle them and deliberately + don't want to log them. But as FreeMarker has already logged that + exception, you will end up one more log entry than expected. To fix + that (since 2.3.22), set the + <code class="inline-code">log_template_exceptions</code> + (<code class="inline-code">Configurable.setLogTemplateExceptions(boolean)</code>) + setting to <code class="inline-code">false</code>.</p> + <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_misc_beanwrapper.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_servlet.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="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>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></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://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="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/pgui_misc_multithreading.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/pgui_misc_multithreading.html b/builds/2.3.26-nightly/pgui_misc_multithreading.html new file mode 100644 index 0000000..1e6d2f0 --- /dev/null +++ b/builds/2.3.26-nightly/pgui_misc_multithreading.html @@ -0,0 +1,73 @@ +<!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>Multithreading - 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="Multithreading"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/pgui_misc_multithreading.html";> +<link rel="canonical" href="http://freemarker.org/docs/pgui_misc_multithreading.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://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?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache FreeMarker Manual"> + + <!--[if lte IE 9]> + <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div> + <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.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="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.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="searc h-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"><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_misc.html"><span itemprop="name">Miscellaneous</span></a></li><li class="step-3" itemprop="it emListElement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="pgui_misc_multithreading.html"><span itemprop="name">Multithreading</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><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","Miscellaneous","Multithreading"];</script> + <script src="toc.js?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></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_misc_charset.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_beanwrapper.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="pgui_misc_multithreading" itemprop="headline">Multithreading</h1> +</div></div><p>In a multithreaded environment <code class="inline-code">Configuration</code> + instances, <code class="inline-code">Template</code> instances and data-models + should be handled as immutable (read-only) objects. That is, you + create and initialize them (for example with + <code class="inline-code">set<em class="code-color">...</em></code> methods), and + then you don't modify them later (e.g. you don't call + <code class="inline-code">set<em class="code-color">...</em></code>). This allows us + to avoid expensive synchronized blocks in a multithreaded environment. + Beware with <code class="inline-code">Template</code> instances; when you get a + <code class="inline-code">Template</code> instance with + <code class="inline-code">Configuration.getTemplate</code>, you may get an instance + from the template cache that is already used by other threads, so do + not call its <code class="inline-code">set<em class="code-color">...</em></code> + methods (calling <code class="inline-code">process</code> is of course fine).</p><p>The above restrictions do not apply if you access all objects + from the <em>same</em> single thread only.</p><p>It is impossible to modify the data-model object or a <a href="pgui_config_sharedvariables.html">shared variable</a> with FTL, + unless you put methods (or other objects) into the data-model that do + that. We discourage you from writing methods that modify the + data-model object or the shared variables. Try to use variables that + are stored in the environment object instead (this object is created + for a single <code class="inline-code">Template.process</code> call to store the + runtime state of processing), so you don't modify data that are + possibly used by multiple threads. For more information read: <a href="pgui_misc_var.html">Variables, scopes</a></p><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_misc_charset.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_beanwrapper.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="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>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></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://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="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html> http://git-wip-us.apache.org/repos/asf/incubator-freemarker-site/blob/52c070a9/builds/2.3.26-nightly/pgui_misc_secureenv.html ---------------------------------------------------------------------- diff --git a/builds/2.3.26-nightly/pgui_misc_secureenv.html b/builds/2.3.26-nightly/pgui_misc_secureenv.html new file mode 100644 index 0000000..3f5a966 --- /dev/null +++ b/builds/2.3.26-nightly/pgui_misc_secureenv.html @@ -0,0 +1,85 @@ +<!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>Configuring security policy for FreeMarker - 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="Configuring security policy for FreeMarker"> +<meta property="og:locale" content="en_US"> +<meta property="og:url" content="http://freemarker.org/docs/pgui_misc_secureenv.html";> +<link rel="canonical" href="http://freemarker.org/docs/pgui_misc_secureenv.html";> +<link rel="icon" href="favicon.png" type="image/png"> +<link rel="stylesheet" type="text/css" href="http://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?1489402528979"> +<script> +(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ +(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), +m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) +})(window,document,'script','//www.google-analytics.com/analytics.js','ga'); +ga('create', 'UA-55420501-1', 'auto'); +ga('send', 'pageview'); +</script> +</head> +<body itemscope itemtype="https://schema.org/Code";> + <meta itemprop="url" content="http://freemarker.org/docs/";> + <meta itemprop="name" content="Apache FreeMarker Manual"> + + <!--[if lte IE 9]> + <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div> + <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org"; role="banner"> <img itemprop="image" src="logo.png" alt="FreeMarker"> +</a><ul class="tabs"><li><a href="http://freemarker.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="http://freemarker.org/contribute.html"; title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://issues.apache.org/jira/browse/FREEMARKER/"; title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.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="searc h-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"><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_misc.html"><span itemprop="name">Miscellaneous</span></a></li><li class="step-3" itemprop="it emListElement" itemscope itemtype="http://schema.org/ListItem";><a class="label" itemprop="item" href="pgui_misc_secureenv.html"><span itemprop="name">Configuring security policy for FreeMarker</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><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","Miscellaneous","Configuring security policy for FreeMarker"];</script> + <script src="toc.js?1489402528979"></script> + <script src="docgen-resources/main.min.js?1489402528979"></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_misc_servlet.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_xml_legacy.html"><span>Next</span></a></div><div class="title-wrapper"> +<h1 class="content-header header-section1" id="pgui_misc_secureenv" itemprop="headline">Configuring security policy for FreeMarker</h1> +</div></div><p>When FreeMarker is used in a Java virtual machine with a + security manager installed, you have to grant it few permissions to + ensure it operates properly. Most notably, you need these entries to + your security policy file for + <code class="inline-code">freemarker.jar</code>:</p> + +<div class="code-wrapper"><pre class="code-block code-unspecified">grant codeBase "file:/path/to/freemarker.jar" +{ + permission java.util.PropertyPermission "file.encoding", "read"; + permission java.util.PropertyPermission "freemarker.*", "read"; +}</pre></div><p>Additionally, if you are loading templates from a directory, you + need to give FreeMarker permissions to read files from that directory + using the following permission:</p> + +<div class="code-wrapper"><pre class="code-block code-unspecified">grant codeBase "file:/path/to/freemarker.jar" +{ + ... + permission java.io.FilePermission "/path/to/templates/-", "read"; +}</pre></div><p>Finally, if you're just using the default template loading + mechanism which loads templates from the current directory, then + specify these permissions additionally: (note that the expression + <code class="inline-code">${user.dir}</code> will be evaluated at run time by the + policy interpreter, pretty much as if it were a FreeMarker + template)</p> + +<div class="code-wrapper"><pre class="code-block code-unspecified"> +grant codeBase "file:/path/to/freemarker.jar" +{ + ... + permission java.util.PropertyPermission "user.dir", "read"; + permission java.io.FilePermission "${user.dir}/-", "read"; +}</pre></div><p>Naturally, if you're running under Windows, use double backslash + instead of a single slash for separating directory components in + paths.</p><div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="pgui_misc_servlet.html"><span>Previous</span></a><a class="paging-arrow next" href="pgui_misc_xml_legacy.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="http://freemarker.org/";>What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html";>Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html";>About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/";>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></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href ="https://github.com/freemarker/freemarker";>FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker";>Follow us on Twitter</a></li><li><a href="https://issues.apache.org/jira/browse/FREEMARKER/";>Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker";>Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html";>Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker";>Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker";>Twitter</a></li><li><a class="stack-overflow" href="http://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="2017-03-13T10:55:28Z" title="Monday, March 13, 2017 10:55:28 AM GMT">2017-03-13 10:55:28 GMT</time>, for Freemarker 2.3.26 </p> +<p class="copyright"> +© <span itemprop="copyrightYear">1999</span>â2017 +<a itemtype="http://schema.org/Organization"; itemprop="copyrightHolder" href="http://apache.org/";>The Apache Software Foundation</a>. Apache FreeMarker, FreeMarker, Apache Incubator, Apache, the Apache FreeMarker logo are trademarks of The Apache Software Foundation. </p> +</div></div></div></body> +</html>
