001// Copyright 2008-2014 The Apache Software Foundation
002//
003// Licensed under the Apache License, Version 2.0 (the "License");
004// you may not use this file except in compliance with the License.
005// You may obtain a copy of the License at
006//
007// http://www.apache.org/licenses/LICENSE-2.0
008//
009// Unless required by applicable law or agreed to in writing, software
010// distributed under the License is distributed on an "AS IS" BASIS,
011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012// See the License for the specific language governing permissions and
013// limitations under the License.
014
015package org.apache.tapestry5;
016
017import org.apache.tapestry5.corelib.base.AbstractField;
018import org.apache.tapestry5.corelib.components.BeanEditForm;
019import org.apache.tapestry5.corelib.components.BeanEditor;
020import org.apache.tapestry5.corelib.mixins.FormGroup;
021import org.apache.tapestry5.internal.services.AssetDispatcher;
022import org.apache.tapestry5.services.assets.AssetPathConstructor;
023import org.apache.tapestry5.services.assets.ResourceMinimizer;
024import org.apache.tapestry5.services.javascript.JavaScriptStack;
025
026/**
027 * Defines the names of symbols used to configure Tapestry.
028 *
029 * @see org.apache.tapestry5.ioc.services.SymbolSource
030 */
031public class SymbolConstants
032{
033    /**
034     * A comma separated list of execution modes used to control how the application is initialized.
035     * Each modes can contribute a list (comma separated) of Module classes to be loaded during startup,
036     * the order in which they appear is preserved.
037     * The default value is: <code>production</code>.
038     */
039    public static final String EXECUTION_MODE = "tapestry.execution-mode";
040    /**
041     * Indicates whether Tapestry is running in production mode or developer mode. This affects a large
042     * number of Tapestry behaviors related to performance and security, including how exceptions are
043     * reported, whether far-future expire headers are emitted, whether JavaScript files may be combined,
044     * whether JSON is compressed, whether component field & parameter values are shadowed to instance
045     * variables (to assist with debugging), and more.
046     */
047    public static final String PRODUCTION_MODE = "tapestry.production-mode";
048
049    /**
050     * A version of {@link #PRODUCTION_MODE} as a symbol reference. This can be used as the default value
051     * of other symbols, to indicate that their default matches whatever PRODUCTION_MODE is set to, which is quite
052     * common.
053     *
054     * @since 5.2.0
055     */
056    public static final String PRODUCTION_MODE_VALUE = String.format("${%s}", PRODUCTION_MODE);
057
058    /**
059     * The list of locales supported by the application; locales identified in the incoming request are "narrowed" to
060     * one of these values. The first locale name in the list is the default locale used when no proper match can be
061     * found.
062     */
063    public static final String SUPPORTED_LOCALES = "tapestry.supported-locales";
064
065    /**
066     * Controls whether whitespace is compressed by default in templates, or left as is. The factory default is to
067     * compress whitespace. (This can also be overridden using the xml:space attribute inside template elements.)
068     */
069    public static final String COMPRESS_WHITESPACE = "tapestry.compress-whitespace";
070
071    /**
072     * Time interval defining how often Tapestry will check for updates to local files (including classes).
073     * Starting with 5.3, this is only used when not running in production mode. The default is "1 s"
074     * (one second), which is appropriate for development. With Tapestry 5.2 and earlier this number
075     * should be raised in a production environment.
076     */
077    public static final String FILE_CHECK_INTERVAL = "tapestry.file-check-interval";
078
079    /**
080     * Time interval that sets how long Tapestry will wait to obtain the exclusive lock needed to check local files. The
081     * default is "50 ms". Starting with 5.3, this is only used when not running in production mode.
082     */
083    public static final String FILE_CHECK_UPDATE_TIMEOUT = "tapestry.file-check-update-timeout";
084
085    /**
086     * The version number of the core Tapestry framework, or UNKNOWN if the version number is not available (which
087     * should only occur when developing Tapestry).
088     */
089    public static final String TAPESTRY_VERSION = "tapestry.version";
090
091    /**
092     * The location of the application-wide component messages catalog, relative to the web application context. This
093     * will normally be <code>WEB-INF/app.properties</code>.
094     */
095    public static final String APPLICATION_CATALOG = "tapestry.app-catalog";
096
097    /**
098     * The charset used when rendering page markup; the charset is also used as the request encoding when handling
099     * incoming requests. The default is "UTF-8".
100     */
101    public static final String CHARSET = "tapestry.charset";
102
103    /**
104     * Used as the default for the Form's autofocus and clientValidation parameters. If overridden to "false", then
105     * Forms will not (unless explicitly specified) use client validation or autofocus, which in turn, means that most
106     * pages with Forms will not make use of the Tapestry JavaScript stack.
107     */
108    public static final String FORM_CLIENT_LOGIC_ENABLED = "tapestry.form-client-logic-enabled";
109
110    /**
111     * Name of page used to report exceptions; the page must implement
112     * {@link org.apache.tapestry5.services.ExceptionReporter}.
113     * This is used by the default exception report handler service.
114     */
115    public static final String EXCEPTION_REPORT_PAGE = "tapestry.exception-report-page";
116
117    /**
118     * Identifies the default persistence strategy for all pages that do not provide an override (using this value as
119     * {@link org.apache.tapestry5.annotations.Meta key}).
120     *
121     * @since 5.1.0.0
122     */
123    public static final String PERSISTENCE_STRATEGY = "tapestry.persistence-strategy";
124
125    /**
126     * Minimum output stream size, in bytes, before output is compressed using GZIP. Shorter streams are not compressed.
127     * Tapestry buffers this amount and switches to a GZIP output stream as needed. The default is "100".
128     *
129     * @see #GZIP_COMPRESSION_ENABLED
130     * @since 5.1.0.0
131     */
132    public static final String MIN_GZIP_SIZE = "tapestry.min-gzip-size";
133
134    /**
135     * Version number of the application. Prior to 5.4, this version number was integrated into asset URLs. Starting
136     * with 5.4, a checksum of the individual asset's content is used instead, and this version number is only used
137     * for documentation purposes; it appears in the default exception report page, for example.
138     * <p/>
139     * The default value is "0.0.1".  In 5.3 and earlier, the default value was a random hexadecimal string.
140     *
141     * @see AssetDispatcher
142     * @see AssetPathConstructor
143     * @since 5.1.0.0
144     */
145    public static final String APPLICATION_VERSION = "tapestry.application-version";
146
147    /**
148     * Used to omit the normal Tapestry framework generator meta tag. The meta tag is rendered by default, but clients
149     * who do not wish to advertise their use of Tapestry may set this symbol to "true".
150     *
151     * @since 5.1.0.0
152     */
153    public static final String OMIT_GENERATOR_META = "tapestry.omit-generator-meta";
154
155    /**
156     * If "true" (the default) then GZip compression is enabled for dynamic requests and for static assets. If you are
157     * using a server that handles GZip compression for you, or you don't want to use the extra processing power
158     * necessary to GZIP requests, then override this to "false".
159     *
160     * @see #MIN_GZIP_SIZE
161     * @see org.apache.tapestry5.services.ResponseCompressionAnalyzer
162     * @see org.apache.tapestry5.services.assets.CompressionAnalyzer
163     * @since 5.1.0.0
164     */
165    public static final String GZIP_COMPRESSION_ENABLED = "tapestry.gzip-compression-enabled";
166
167    /**
168     * If "true" (which itself defaults to production mode), then the {@link org.apache.tapestry5.annotations.Secure}
169     * annotation will be honored. If "false" (i.e., development mode), then the annotation and related HTTP/HTTPS
170     * logic is ignored.
171     *
172     * @since 5.1.0.1
173     */
174    public static final String SECURE_ENABLED = "tapestry.secure-enabled";
175
176    /**
177     * If "true" (the default), then the {@link org.apache.tapestry5.services.PersistentLocale} will be encoded into the
178     * {@link org.apache.tapestry5.Link} path by the {@link org.apache.tapestry5.services.ComponentEventLinkEncoder}
179     * service. If overridden to "false" this does not occur, but you should provide a
180     * {@link org.apache.tapestry5.services.LinkCreationListener2} (registered with the
181     * {@link org.apache.tapestry5.services.LinkCreationHub}) in order to add the locale as a query parameter (or
182     * provide some alternate means of persisting the locale between requests).
183     *
184     * @since 5.1.0.1
185     */
186    public static final String ENCODE_LOCALE_INTO_PATH = "tapestry.encode-locale-into-path";
187
188    /**
189     * If "true" then JavaScript files in a {@link JavaScriptStack} will be combined into a single virtual JavaScript
190     * file. Defaults to "true" in production mode.
191     *
192     * @since 5.1.0.2
193     */
194    public static final String COMBINE_SCRIPTS = "tapestry.combine-scripts";
195
196
197    /**
198     * The default time interval that cookies created by Tapestry will be kept in the client web browser. The default is
199     * "7 d" (that is, seven days).
200     *
201     * @since 5.2.0
202     */
203    public static final String COOKIE_MAX_AGE = "tapestry.default-cookie-max-age";
204
205    /**
206     * The logical name of the start page, the page that is rendered for the root URL.
207     *
208     * @since 5.2.0
209     */
210    public static final String START_PAGE_NAME = "tapestry.start-page-name";
211
212    /**
213     * The default stylesheet automatically inserted into every rendered HTML page.
214     *
215     * @since 5.2.0
216     * @deprecated Deprecated in 5.4 with no replacement; the stylesheet is now associated with the core {@link JavaScriptStack}.
217     */
218    public static final String DEFAULT_STYLESHEET = "tapestry.default-stylesheet";
219
220    /**
221     * The Asset path to the embedded copy of script.aculo.us packaged with Tapestry.
222     *
223     * @since 5.2.0
224     */
225    public static final String SCRIPTACULOUS = "tapestry.scriptaculous";
226
227    /**
228     * The Asset path to the embedded datepicker.
229     *
230     * @since 5.2.0
231     */
232    public static final String DATEPICKER = "tapestry.datepicker";
233
234    /**
235     * If "true", then JSON page initialization content is compressed; if "false"
236     * then extra white space is added (pretty printing). Defaults to "true" in production mode.
237     *
238     * @since 5.2.0
239     */
240    public static final String COMPACT_JSON = "tapestry.compact-json";
241
242    /**
243     * If "true" and {@link #PRODUCTION_MODE} is off, comments will be rendered before and after the rendering of any
244     * component
245     * allowing more visibility into which components rendered which markup. Defaults to "false". Component render
246     * tracing may be
247     * enabled per-request by the presence of a request parameter "t:component-trace" with a value of "true".
248     *
249     * @since 5.2.5
250     */
251    public static final String COMPONENT_RENDER_TRACING_ENABLED = "tapestry.component-render-tracing-enabled";
252
253    /**
254     * The hostname that application should use when constructing an absolute URL. The default is "", i.e. an empty
255     * string,
256     * in which case system will use request.getServerName(). Not the same as environment variable HOSTNAME, but you can
257     * also
258     * contribute "$HOSTNAME" as the value to make it the same as the environment variable HOSTNAME.
259     *
260     * @since 5.3
261     */
262    public static final String HOSTNAME = "tapestry.hostname";
263
264    /**
265     * The hostport that application should use when constructing an absolute URL. The default is "0", i.e. use the port
266     * value from
267     * the request.
268     *
269     * @since 5.3
270     */
271    public static final String HOSTPORT = "tapestry.hostport";
272
273    /**
274     * The secure (https) hostport that application should use when constructing an absolute URL. The default is "0",
275     * i.e. use
276     * the value from the request.
277     *
278     * @since 5.3
279     */
280    public static final String HOSTPORT_SECURE = "tapestry.hostport-secure";
281
282    /**
283     * If "true", then resources (individually or when aggregated into stacks) will be minimized via the
284     * {@link ResourceMinimizer} service. If "false", then minification is disabled. Tracks production mode
285     * (minification is normally disabled in development mode).
286     * <p/>
287     * Note that Tapestry's default implementation of {@link ResourceMinimizer} does nothing; minification is provided
288     * by add-on libraries.
289     *
290     * @since 5.3
291     */
292    public static final String MINIFICATION_ENABLED = "tapestry.enable-minification";
293
294    /**
295     * If "true" then at the end of each request the
296     * {@link org.apache.tapestry5.services.SessionPersistedObjectAnalyzer} will be called on each session persisted
297     * object that was accessed during the request.
298     * <p/>
299     * This is provided as a performance enhancement for servers that do not use clustered sessions.
300     * <p/>
301     * The default is {@code true}, to preserve 5.2 behavior. For non-clustered applications (the majority), this value should be
302     * overridden to {@code false}. A future release of Tapestry may change the default.
303     *
304     * @since 5.3
305     */
306    public static final String CLUSTERED_SESSIONS = "tapestry.clustered-sessions";
307
308    /**
309     * The name of a folder in which the Tapestry application executes. Prior to 5.3, a Tapestry application always responded to all
310     * URLs in the context under the context root; by setting this to the name of a folder, the T5 URLs will be inside that folder only, and should
311     * match a corresponding entry in the {@code web.xml} configuration file.  This is useful when running multiple servlets within the same web application (such as when migrating
312     * from Tapestry 4 or some other framework, to Tapestry 5).
313     * <p>Effectively, if this symbol is set to a value, that folder name will be placed after the context path
314     * (typically "/") and before the locale, page name, or other prefix.  For example, if this symbol is set to "app", the {@code web.xml <url-pattern>} should be set to {@code /app/*}, and Tapestry will
315     * only be in invoked by the servlet container for requests inside the virtual {@code app} folder.
316     * <p/>
317     * This also affects the search for page templates (which are allowed within the web context). When set to a non-blank value, page templates are searched for in the folder, rather than in the root context.
318     * <p/>
319     * The default value is the empty string, which preserves Tapestry 5.2 behavior (and continues to be appropriate for most applications).
320     * <p/>
321     * Note that while Tapestry is case-insensitive, the servlet container is not, so the configured value must exactly match
322     * the folder name inside the {@code <url-parameter>} value, including case.
323     *
324     * @since 5.3
325     */
326    public static final String APPLICATION_FOLDER = "tapestry.application-folder";
327
328    /**
329     * Boolean value to indicate if every {@link  org.apache.tapestry5.Asset2} should be fully qualified or not.
330     * Default to <code>false</code> meaning no Asset URL will be fully qualified.
331     *
332     * @since 5.3
333     */
334    public static final String ASSET_URL_FULL_QUALIFIED = "tapestry.asset-url-fully-qualified";
335
336    /**
337     * Prefix to be used for all resource paths, used to recognize which requests are for assets. This value
338     * is appended to the context path and the (optional {@linkplain #APPLICATION_FOLDER application folder}.
339     * It may contain slashes, but should not begin or end with one.
340     * <p/>
341     * The default is "assets".
342     */
343    public static final String ASSET_PATH_PREFIX = "tapestry.asset-path-prefix";
344
345
346    /**
347     * Prefix used for all module resources. This may contain slashes, but should not being or end with one.
348     * Tapestry will create two {@link org.apache.tapestry5.services.Dispatcher}s from this: one for normal
349     * modules, the other for GZip compressed modules (by appending ".gz" to this value).
350     * <p/>
351     * The default is "modules".
352     *
353     * @since 5.4
354     */
355    public static final String MODULE_PATH_PREFIX = "tapestry.module-path-prefix";
356
357    /**
358     * Identifies the context path of the application, as determined from {@link javax.servlet.ServletContext#getContextPath()}.
359     * This is either a blank string or a string that starts with a slash but does not end with one.
360     *
361     * @since 5.4
362     */
363    public static final String CONTEXT_PATH = "tapestry.context-path";
364
365    /**
366     * A passphrase used as the basis of hash-based message authentication (HMAC) for any object stream data stored on
367     * the client.  The default phrase is the empty string, which will result in a logged runtime <em>error</em>.
368     * You should configure this to a reasonable value (longer is better) and ensure that all servers in your cluster
369     * share the same value (configuring this in code, rather than the command line, is preferred).
370     *
371     * @see org.apache.tapestry5.services.ClientDataEncoder
372     * @since 5.3.6
373     */
374    public static final String HMAC_PASSPHRASE = "tapestry.hmac-passphrase";
375
376    /**
377     * The root asset path for Twitter Bootstrap; if your application uses a modified version of Bootstrap,
378     * you can override this symbol to have Tapestry automatically use your version. The value should be a path
379     * to a folder (under "classpath:" or "context:") and should not include a trailing slash.
380     *
381     * @since 5.4
382     */
383    public static final String BOOTSTRAP_ROOT = "tapestry.bootstrap-root";
384
385    /**
386     * Tapestry relies on an underlying client-side JavaScript infrastructure framework to handle DOM manipulation,
387     * event handling, and Ajax requests. Through Tapestry 5.3, the foundation was
388     * <a href="http://http://prototypejs.org/">Prototype</a>. In 5.4, support for
389     * <a href="http://jquery.org/">jQuery</a> has been added, and it is possible to add others. This symbol defines a value that is used to select
390     * a resource that is provided to the {@link org.apache.tapestry5.services.javascript.ModuleManager} service
391     * as a {@link org.apache.tapestry5.services.javascript.JavaScriptModuleConfiguration} to provide a specific implementation
392     * of the {@code t5/core/dom} module. Tapestry 5.4 directly supports "prototype" or "jquery".  To support
393     * other foundation frameworks, override this symbol value and supply your own module configuration.
394     * <p/>
395     * In Tapestry 5.4, this defaults to "prototype" for compatibility with 5.3. This will likely change in
396     * 5.5 to default to "jquery". At some point in the future, Prototype support will no longer be present.
397     *
398     * @since 5.4
399     */
400    public static final String JAVASCRIPT_INFRASTRUCTURE_PROVIDER = "tapestry.javascript-infrastructure-provider";
401
402    /**
403     * If true (the default), then Tapestry will apply locking semantics around access to the {@link javax.servlet.http.HttpSession}.
404     * Reading attribute names occurs with a shared read lock; getting or setting an attribute upgrades to an exclusive write lock.
405     * This can tend to serialize threads when a number of simultaneous (Ajax) requests from the client arrive ... however,
406     * many implementations of HttpSession are not thread safe, and often mutable objects are stored in the session and shared
407     * between threads. Leaving this on the default will yield a more robust application; setting it to false may speed
408     * up processing for more Ajax intensive applications (but care should then be given to ensuring that objects shared inside
409     * the session are themselves immutable or thread-safe).
410     *
411     * @since 5.4
412     */
413    public static final String SESSION_LOCKING_ENABLED = "tapestry.session-locking-enabled";
414
415    /**
416     * If true (the default), then Tapestry will automatically include the "core" stack in all
417     * pages.
418     *
419     * @see https://issues.apache.org/jira/browse/TAP5-2169
420     * @since 5.4
421     */
422    public static final String INCLUDE_CORE_STACK = "tapestry.include-core-stack";
423
424    /**
425     * Defines the CSS class that will be given to HTML element (usually a div) &lt;div&gt; generated by
426     * the {@linkplain FormGroup} mixin and the
427     * {@linkplain BeanEditForm} and {@linkplain BeanEditor}
428     * components surrounding the label and the field. The default value is <code>form-group</code>.
429     *
430     * @see https://issues.apache.org/jira/browse/TAP5-2182
431     * @since 5.4
432     */
433    public static final String FORM_GROUP_WRAPPER_CSS_CLASS = "tapestry.form-group-wrapper-css-class";
434
435    /**
436     * Defines the name of the HTML element that will surround the HTML form field generated by
437     * the {@linkplain FormGroup} mixin and the {@linkplain BeanEditForm} and {@linkplain BeanEditor}.
438     * If this symbol is null or an empty string, no element will be generated surrouding the
439     * form field. The default value is the empty string (no wrapping).
440     *
441     * @see https://issues.apache.org/jira/browse/TAP5-2182
442     * @see #FORM_GROUP_FORM_FIELD_WRAPPER_ELEMENT_CSS_CLASS
443     * @since 5.4
444     */
445    public static final String FORM_GROUP_FORM_FIELD_WRAPPER_ELEMENT_NAME = "tapestry.form-group-form-field-wrapper-element-name";
446
447    /**
448     * Defines the CSS class of the HTML element generated by
449     * the {@linkplain FormGroup} mixin and the {@linkplain BeanEditForm} and {@linkplain BeanEditor}.
450     * when {@linkplain FORM_GROUP_FORM_FIELD_WRAPPER_ELEMENT_NAME} is not set to null or the empty string.
451     * The default value is the empty string (no CSS class added).
452     *
453     * @see https://issues.apache.org/jira/browse/TAP5-2182
454     * @since 5.4
455     */
456    public static final String FORM_GROUP_FORM_FIELD_WRAPPER_ELEMENT_CSS_CLASS = "tapestry.form-group-form-field-wrapper-element-css-class";
457
458    /**
459     * Defines the CSS class that will be given to &lt;label&gt; element generated by
460     * the {@linkplain FormGroup} mixin and the
461     * {@linkplain BeanEditForm} and {@linkplain BeanEditor}
462     * components. The default value is <code>control-label</code>.
463     *
464     * @see https://issues.apache.org/jira/browse/TAP5-2182
465     * @since 5.4
466     */
467    public static final String FORM_GROUP_LABEL_CSS_CLASS = "tapestry.form-group-label-css-class";
468
469    /**
470     * Defines the CSS class that will be given to form field components which are
471     * {@linkplain AbstractField} subclasses. The default value is <code>form-control</code>.
472     *
473     * @see https://issues.apache.org/jira/browse/TAP5-2182
474     * @since 5.4
475     */
476    public static final String FORM_FIELD_CSS_CLASS = "tapestry.form-field-css-class";
477    
478    /**
479     * Defines whether {@link java.text.DateFormat} instances created by Tapestry should be
480     * lenient or not by default. The default value is <code>false</code>.
481     * @since 5.4
482     */
483    public static final String LENIENT_DATE_FORMAT = "tapestry.lenient-date-format";
484
485}