| /* |
| * Copyright (C) 2010 Google Inc. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package com.google.clearsilver.jsilver; |
| |
| import com.google.clearsilver.jsilver.autoescape.EscapeMode; |
| import com.google.clearsilver.jsilver.data.NoOpStringInternStrategy; |
| import com.google.clearsilver.jsilver.data.StringInternStrategy; |
| |
| import java.util.Map; |
| |
| /** |
| * Options for JSilver. |
| * |
| * Note: Setter methods also return reference to this, allowing options to be defined in one |
| * statement. |
| * |
| * e.g. new JSilver(..., new JSilverOptions().setSomething(true).setAnother(false)); |
| * |
| * @see JSilver |
| */ |
| public class JSilverOptions implements Cloneable { |
| |
| private boolean cacheTemplates = true; |
| private boolean compileTemplates = false; |
| private int initialBufferSize = 8192; |
| private boolean ignoreAttributes = false; |
| private Map<Object, String> precompiledTemplateMap = null; |
| private boolean useStrongCacheReferences = false; |
| private EscapeMode escapeMode = EscapeMode.ESCAPE_NONE; |
| private boolean propagateEscapeStatus = false; |
| |
| /** |
| * A pool of strings used to optimize HDF parsing. |
| * |
| * String interning has been shown to improve GC performance, but also to increase CPU usage. To |
| * avoid any possible unexpected changes in behavior it is disabled by default. |
| */ |
| private StringInternStrategy stringInternStrategy = new NoOpStringInternStrategy(); |
| |
| /** |
| * This flag is used to enable logging of all variables whose values are modified by auto escaping |
| * or <cs escape> commands. These will be logged at {@code Level.WARNING}. |
| */ |
| private boolean logEscapedVariables = false; |
| private boolean useOutputBufferPool = false; |
| private boolean stripHtmlWhiteSpace = false; |
| private boolean stripStructuralWhiteSpace = false; |
| private boolean allowGlobalDataModification = false; |
| private boolean keepTemplateCacheFresh = false; |
| private int loadPathCacheSize = 1000; |
| |
| // When adding fields, ensure you: |
| // * add getter. |
| // * add setter (which returns this). |
| // * add to clone() method if necessary. |
| |
| /** |
| * Set the initial size of the load path cache container. Setting this to 0 causes load path cache |
| * to be disabled. |
| */ |
| public JSilverOptions setLoadPathCacheSize(int loadPathCacheSize) { |
| this.loadPathCacheSize = loadPathCacheSize; |
| return this; |
| } |
| |
| /** |
| * @see #setLoadPathCacheSize(int) |
| */ |
| public int getLoadPathCacheSize() { |
| return loadPathCacheSize; |
| } |
| |
| /** |
| * Whether to cache templates. This will only ever load and parse a template from disk once. Best |
| * switched on for production but left off for production (so you can update templates without |
| * restarting). |
| */ |
| public JSilverOptions setCacheTemplates(boolean cacheTemplates) { |
| this.cacheTemplates = cacheTemplates; |
| return this; |
| } |
| |
| /** |
| * @see #setCacheTemplates(boolean) |
| */ |
| public boolean getCacheTemplates() { |
| return cacheTemplates; |
| } |
| |
| /** |
| * Compile templates to Java byte code. This slows down the initial render as it performs a |
| * compilation step, but then subsequent render are faster. |
| * |
| * Compiled templates are always cached. |
| * |
| * WARNING: This functionality is experimental. Use with caution. |
| */ |
| public JSilverOptions setCompileTemplates(boolean compileTemplates) { |
| this.compileTemplates = compileTemplates; |
| return this; |
| } |
| |
| /** |
| * @see #setCompileTemplates(boolean) |
| */ |
| public boolean getCompileTemplates() { |
| return compileTemplates; |
| } |
| |
| /** |
| * If set, then HDF attributes in HDF files will be ignored and not stored in the Data object |
| * filled by the parser. Default is {@code false}. Many applications use HDF attributes only in |
| * template preprocessing (like translation support) and never in production servers where the |
| * templates are rendered. By disabling attribute parsing, these applications can save on memory |
| * for storing HDF structures read from files. |
| */ |
| public JSilverOptions setIgnoreAttributes(boolean ignoreAttributes) { |
| this.ignoreAttributes = ignoreAttributes; |
| return this; |
| } |
| |
| /** |
| * @see #setIgnoreAttributes(boolean) |
| */ |
| public boolean getIgnoreAttributes() { |
| return ignoreAttributes; |
| } |
| |
| /** |
| * Initial buffer size used when rendering directly to a string. |
| */ |
| public JSilverOptions setInitialBufferSize(int initialBufferSize) { |
| this.initialBufferSize = initialBufferSize; |
| return this; |
| } |
| |
| /** |
| * @see #setInitialBufferSize(int) |
| */ |
| public int getInitialBufferSize() { |
| return initialBufferSize; |
| } |
| |
| /** |
| * Optional mapping of TemplateLoader keys to Template instances that will be queried when loading |
| * a template. If the Template is found it is returned. If not, the next template loader is |
| * consulted. |
| * |
| * @param precompiledTemplateMap map of TemplateLoader keys to corresponding class names that |
| * should be valid BaseCompiledTemplate subclasses. Set to {@code null} (default) to not |
| * load precompiled templates. |
| */ |
| public JSilverOptions setPrecompiledTemplateMap(Map<Object, String> precompiledTemplateMap) { |
| this.precompiledTemplateMap = precompiledTemplateMap; |
| return this; |
| } |
| |
| /** |
| * @see #setPrecompiledTemplateMap(java.util.Map) |
| * @return a mapping of TemplateLoader keys to corresponding BaseCompiledTemplate class names, or |
| * {@code null} (default) if no precompiled templates should be preloaded. |
| */ |
| public Map<Object, String> getPrecompiledTemplateMap() { |
| return precompiledTemplateMap; |
| } |
| |
| /** |
| * If {@code true}, then the template cache will use strong persistent references for the values. |
| * If {@code false} (default) it will use soft references. Warning: The cache size is unbounded so |
| * only use this option if you have sufficient memory to load all the Templates into memory. |
| */ |
| public JSilverOptions setUseStrongCacheReferences(boolean value) { |
| this.useStrongCacheReferences = value; |
| return this; |
| } |
| |
| /** |
| * @see #setUseStrongCacheReferences(boolean) |
| */ |
| public boolean getUseStrongCacheReferences() { |
| return useStrongCacheReferences; |
| } |
| |
| /** |
| * @see #setEscapeMode(com.google.clearsilver.jsilver.autoescape.EscapeMode) |
| */ |
| public EscapeMode getEscapeMode() { |
| return escapeMode; |
| } |
| |
| /** |
| * Escape any template being rendered with the given escaping mode. If the mode is ESCAPE_HTML, |
| * ESCAPE_URL or ESCAPE_JS, the corresponding escaping will be all variables in the template. If |
| * the mode is ESCAPE_AUTO, enable <a href="http://go/autoescapecs">auto escaping</a> on |
| * templates. For each variable in the template, this will determine what type of escaping should |
| * be applied to the variable, and automatically apply this escaping. This flag can be overriden |
| * by setting appropriate HDF variables before loading a template. If Config.AutoEscape is 1, auto |
| * escaping is enabled. If Config.VarEscapeMode is set to one of 'html', 'js' or 'url', the |
| * corresponding escaping is applied to all variables. |
| * |
| * @param escapeMode |
| */ |
| public JSilverOptions setEscapeMode(EscapeMode escapeMode) { |
| this.escapeMode = escapeMode; |
| return this; |
| } |
| |
| /** |
| * @see #setPropagateEscapeStatus |
| */ |
| public boolean getPropagateEscapeStatus() { |
| return propagateEscapeStatus; |
| } |
| |
| /** |
| * Only used for templates that are being <a href="http://go/autoescapecs">auto escaped</a>. If |
| * {@code true} and auto escaping is enabled, variables created by <cs set> or <cs |
| * call> commands are not auto escaped if they are assigned constant or escaped values. This is |
| * disabled by default. |
| * |
| * @see #setEscapeMode |
| */ |
| public JSilverOptions setPropagateEscapeStatus(boolean propagateEscapeStatus) { |
| this.propagateEscapeStatus = propagateEscapeStatus; |
| return this; |
| } |
| |
| /** |
| * Sets the {@link StringInternStrategy} object that will be used to optimize HDF parsing. |
| * |
| * <p> |
| * Set value should not be {@code null} as it can cause {@link NullPointerException}. |
| * |
| * @param stringInternStrategy - {@link StringInternStrategy} object |
| */ |
| public void setStringInternStrategy(StringInternStrategy stringInternStrategy) { |
| if (stringInternStrategy == null) { |
| throw new IllegalArgumentException("StringInternStrategy should not be null."); |
| } |
| this.stringInternStrategy = stringInternStrategy; |
| } |
| |
| /** |
| * Returns {@link StringInternStrategy} object that is used for optimization of HDF parsing. |
| * |
| * <p> |
| * The returned value should never be {@code null}. |
| * |
| * @return currently used {@link StringInternStrategy} object. |
| */ |
| public StringInternStrategy getStringInternStrategy() { |
| return stringInternStrategy; |
| } |
| |
| /** |
| * If {@code true}, then use a threadlocal buffer pool for holding rendered output when outputting |
| * to String. Assumes that render() is called from a thread and that thread will not reenter |
| * render() while it is running. If {@code false}, a new buffer is allocated for each request |
| * where an Appendable output object was not provided. |
| */ |
| public JSilverOptions setUseOutputBufferPool(boolean value) { |
| this.useOutputBufferPool = value; |
| return this; |
| } |
| |
| /** |
| * @see #setUseOutputBufferPool(boolean) |
| */ |
| public boolean getUseOutputBufferPool() { |
| return useOutputBufferPool; |
| } |
| |
| /** |
| * If {@code true}, then unnecessary whitespace will be stripped from the output. 'Unnecessary' is |
| * meant in terms of HTML output. See |
| * {@link com.google.clearsilver.jsilver.template.HtmlWhiteSpaceStripper} for more info. |
| */ |
| public JSilverOptions setStripHtmlWhiteSpace(boolean value) { |
| this.stripHtmlWhiteSpace = value; |
| return this; |
| } |
| |
| /** |
| * @see #setStripHtmlWhiteSpace(boolean) |
| */ |
| public boolean getStripHtmlWhiteSpace() { |
| return stripHtmlWhiteSpace; |
| } |
| |
| /** |
| * If {@code true}, then structural whitespace will be stripped from the output. This allows |
| * templates to be written to more closely match normal programming languages. See |
| * {@link com.google.clearsilver.jsilver.syntax.StructuralWhitespaceStripper} for more info. |
| */ |
| public JSilverOptions setStripStructuralWhiteSpace(boolean value) { |
| this.stripStructuralWhiteSpace = value; |
| return this; |
| } |
| |
| /** |
| * @see #setStripHtmlWhiteSpace(boolean) |
| */ |
| public boolean getStripStructuralWhiteSpace() { |
| return stripStructuralWhiteSpace; |
| } |
| |
| /** |
| * Use this method to disable wrapping the global HDF with an UnmodifiableData object which |
| * prevents modification. This flag is here in case there are corner cases or performance reasons |
| * that someone may want to disable this protection. |
| * |
| * Should not be set to {@code true} unless incompatibilities or performance issues found. Note, |
| * that setting to {@code true} could introduce bugs in templates that acquire local references to |
| * the global data structure and then try to modify them, which is not the intended behavior. |
| * Allowing global data modification during rendering is not compatible with the recently fixed |
| * JNI Clearsilver library. |
| * |
| * TODO: Remove once legacy mode is no longer needed. |
| * |
| * @param allowGlobalDataModification {@code true} if you want to avoid wrapping the global HDF so |
| * that all writes to it during rendering are prevented and throw an exception. |
| * @return this object. |
| */ |
| public JSilverOptions setAllowGlobalDataModification(boolean allowGlobalDataModification) { |
| this.allowGlobalDataModification = allowGlobalDataModification; |
| return this; |
| } |
| |
| /** |
| * @see #setAllowGlobalDataModification(boolean) |
| */ |
| public boolean getAllowGlobalDataModification() { |
| return allowGlobalDataModification; |
| } |
| |
| /** |
| * @param keepTemplateCacheFresh {@code true} to have the template cache call |
| * {@link com.google.clearsilver.jsilver.resourceloader.ResourceLoader#getResourceVersionId(String)} |
| * to check if it should refresh its cache entries (this incurs a small performance penalty |
| * each time the cache is accessed) |
| * @return this object |
| */ |
| public JSilverOptions setKeepTemplateCacheFresh(boolean keepTemplateCacheFresh) { |
| this.keepTemplateCacheFresh = keepTemplateCacheFresh; |
| return this; |
| } |
| |
| /** |
| * @see #setKeepTemplateCacheFresh(boolean) |
| */ |
| public boolean getKeepTemplateCacheFresh() { |
| return keepTemplateCacheFresh; |
| } |
| |
| @Override |
| public JSilverOptions clone() { |
| try { |
| return (JSilverOptions) super.clone(); |
| } catch (CloneNotSupportedException impossible) { |
| throw new AssertionError(impossible); |
| } |
| } |
| |
| /** |
| * @see #setLogEscapedVariables |
| */ |
| public boolean getLogEscapedVariables() { |
| return logEscapedVariables; |
| } |
| |
| /** |
| * Use this method to enable logging of all variables whose values are modified by auto escaping |
| * or <cs escape> commands. These will be logged at {@code Level.WARNING}. This is useful |
| * for detecting variables that should be exempt from auto escaping. |
| * |
| * <p> |
| * It is recommended to only enable this flag during testing or debugging and not for production |
| * jobs. |
| * |
| * @see #setEscapeMode |
| */ |
| public JSilverOptions setLogEscapedVariables(boolean logEscapedVariables) { |
| this.logEscapedVariables = logEscapedVariables; |
| return this; |
| } |
| } |