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