    001    // Copyright 2008, 2009, 2010, 2011 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
    015    package org.apache.tapestry5;
    016
    017    import org.apache.tapestry5.internal.services.AssetDispatcher;
    018    import org.apache.tapestry5.services.assets.AssetPathConstructor;
    019    import org.apache.tapestry5.services.assets.ResourceMinimizer;
    020    import org.apache.tapestry5.services.javascript.JavaScriptStack;
    021
    022    /**
    023     * Defines the names of symbols used to configure Tapestry.
    024     *
    025     * @see org.apache.tapestry5.ioc.services.SymbolSource
    026     */
    027    public class SymbolConstants
    028    {
    029        /**
    030         * A comma separated list of execution modes used to control how the application is initialized.
    031         * Each modes can contribute a list (comma separated) of Module classes to be loaded during startup,
    032         * the order in which they appear is preserved.
    033         * The default value is: <code>production</code>.
    034         */
    035        public static final String EXECUTION_MODE = "tapestry.execution-mode";
    036        /**
    037         * Indicates whether Tapestry is running in production mode or developer mode. The primary difference is how
    038         * exceptions are reported.
    039         */
    040        public static final String PRODUCTION_MODE = "tapestry.production-mode";
    041
    042        /**
    043         * A version of {@link #PRODUCTION_MODE} as a symbol reference. This can be used as the default value
    044         * of other symbols, to indicate that their default matches whatever PRODUCTION_MODE is set to, which is quite
    045         * common.
    046         *
    047         * @since 5.2.0
    048         */
    049        public static final String PRODUCTION_MODE_VALUE = String.format("${%s}", PRODUCTION_MODE);
    050
    051        /**
    052         * If set to "true", then action requests will render a page markup response immediately, rather than sending a
    053         * redirect to render the response. "Action request" is an outdated term for "component event request" (i.e., most
    054         * links and all form submissions).
    055         *
    056         * @deprecated In 5.3, to be removed (along with the support it implies) in 5.4
    057         */
    058        @Deprecated
    059        public static final String SUPPRESS_REDIRECT_FROM_ACTION_REQUESTS = "tapestry.suppress-redirect-from-action-requests";
    060
    061        /**
    062         * The list of locales supported by the application; locales identified in the incoming request are "narrowed" to
    063         * one of these values. The first locale name in the list is the default locale used when no proper match can be
    064         * found.
    065         */
    066        public static final String SUPPORTED_LOCALES = "tapestry.supported-locales";
    067
    068        /**
    069         * Controls whether whitespace is compressed by default in templates, or left as is. The factory default is to
    070         * compress whitespace. This can be overridden using the xml:space attribute inside template elements.
    071         */
    072        public static final String COMPRESS_WHITESPACE = "tapestry.compress-whitespace";
    073
    074        /**
    075         * Time interval defining how often Tapestry will check for updates to local files (including classes). This number
    076         * can be raised in a production environment. The default is "1 s" (one second), which is appropriate for
    077         * development.
    078         */
    079        public static final String FILE_CHECK_INTERVAL = "tapestry.file-check-interval";
    080
    081        /**
    082         * Time interval that sets how long Tapestry will wait to obtain the exclusive lock needed to check local files. The
    083         * default is "50 ms".
    084         */
    085        public static final String FILE_CHECK_UPDATE_TIMEOUT = "tapestry.file-check-update-timeout";
    086
    087        /**
    088         * The version number of the core Tapestry framework, or UNKNOWN if the version number is not available (which
    089         * should only occur when developing Tapestry).
    090         */
    091        public static final String TAPESTRY_VERSION = "tapestry.version";
    092
    093        /**
    094         * The location of the application-wide component messages catalog, relative to the web application context. This
    095         * will normally be <code>WEB-INF/app.properties</code>.
    096         */
    097        public static final String APPLICATION_CATALOG = "tapestry.app-catalog";
    098
    099        /**
    100         * The charset used when rendering page markup; the charset is also used as the request encoding when handling
    101         * incoming requests. The default is "UTF-8".
    102         */
    103        public static final String CHARSET = "tapestry.charset";
    104
    105        /**
    106         * Used as the default for the Form's autofocus and clientValidation parameters. If overridden to "false", then
    107         * Forms will not (unless explicitly specified) use client validation or autofocus, which in turn, means that most
    108         * pages with Forms will not make use of the Tapestry JavaScript stack.
    109         */
    110        public static final String FORM_CLIENT_LOGIC_ENABLED = "tapestry.form-client-logic-enabled";
    111
    112        /**
    113         * Name of page used to report exceptions; the page must implement
    114         * {@link org.apache.tapestry5.services.ExceptionReporter}.
    115         * This is used by the default exception report handler service.
    116         */
    117        public static final String EXCEPTION_REPORT_PAGE = "tapestry.exception-report-page";
    118
    119        /**
    120         * Identifies the default persistence strategy for all pages that do not provide an override (using this value as
    121         * {@link org.apache.tapestry5.annotations.Meta key}).
    122         *
    123         * @since 5.1.0.0
    124         */
    125        public static final String PERSISTENCE_STRATEGY = "tapestry.persistence-strategy";
    126
    127        /**
    128         * Minimum output stream size, in bytes, before output is compressed using GZIP. Shorter streams are not compressed.
    129         * Tapestry buffers this amount and switches to a GZIP output stream as needed. The default is "100".
    130         *
    131         * @see #GZIP_COMPRESSION_ENABLED
    132         * @since 5.1.0.0
    133         */
    134        public static final String MIN_GZIP_SIZE = "tapestry.min-gzip-size";
    135
    136        /**
    137         * Version number integrated into URLs for assets. This should be changed for each release, otherwise
    138         * out-of-date files may be used from the client's local cache (due to far-future expired headers). The default
    139         * value is semi-random and different for each execution, which will adversely affect client caching, but is
    140         * reasonable
    141         * for development.
    142         *
    143         * @see AssetDispatcher
    144         * @see AssetPathConstructor
    145         * @since 5.1.0.0
    146         */
    147        public static final String APPLICATION_VERSION = "tapestry.application-version";
    148
    149        /**
    150         * Used to omit the normal Tapestry framework generator meta tag. The meta tag is rendered by default, but clients
    151         * who do not wish to advertise their use of Tapestry may set this symbol to "true".
    152         *
    153         * @since 5.1.0.0
    154         */
    155        public static final String OMIT_GENERATOR_META = "tapestry.omit-generator-meta";
    156
    157        /**
    158         * If "true" (the default) then GZip compression is enabled for dynamic requests and for static assets. If you are
    159         * using a server that handles GZip compression for you, or you don't want to ue the extra processing power
    160         * necessary to GZIP requests, then override this to "false".
    161         *
    162         * @see #MIN_GZIP_SIZE
    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         * If "true" then Blackbird JavaScript console is enabled.
    198         *
    199         * @since 5.2.0
    200         * @deprecated in 5.3, with no replacement (due to removal of Blackbird console entirely)
    201         */
    202        public static final String BLACKBIRD_ENABLED = "tapestry.blackbird-enabled";
    203
    204        /**
    205         * The default time interval that cookies created by Tapestry will be kept in the client web browser. The default is
    206         * "7 d" (that is, seven days).
    207         *
    208         * @since 5.2.0
    209         */
    210        public static final String COOKIE_MAX_AGE = "tapestry.default-cookie-max-age";
    211
    212        /**
    213         * The logical name of the start page, the page that is rendered for the root URL.
    214         *
    215         * @since 5.2.0
    216         */
    217        public static final String START_PAGE_NAME = "tapestry.start-page-name";
    218
    219        /**
    220         * The default stylesheet automatically injected into every rendered HTML page.
    221         *
    222         * @since 5.2.0
    223         */
    224        public static final String DEFAULT_STYLESHEET = "tapestry.default-stylesheet";
    225
    226        /**
    227         * The Asset path to the embedded copy of script.aculo.us packaged with Tapestry.
    228         *
    229         * @since 5.2.0
    230         */
    231        public static final String SCRIPTACULOUS = "tapestry.scriptaculous";
    232
    233        /**
    234         * The Asset path to the embedded datepicker.
    235         *
    236         * @since 5.2.0
    237         */
    238        public static final String DATEPICKER = "tapestry.datepicker";
    239
    240        /**
    241         * The Asset path to the embedded copy of blackbird packaged with Tapestry.
    242         *
    243         * @since 5.2.0
    244         * @deprecated in 5.3 with no replacement
    245         */
    246        public static final String BLACKBIRD = "tapestry.blackbird";
    247
    248        /**
    249         * If "true", then JSON page initialization content is compressed; if "false"
    250         * then extra white space is added (pretty printing). Defaults to "true" in production mode.
    251         *
    252         * @since 5.2.0
    253         */
    254        public static final String COMPACT_JSON = "tapestry.compact-json";
    255
    256        /**
    257         * If "true" and {@link #PRODUCTION_MODE} is off, comments will be rendered before and after the rendering of any
    258         * component
    259         * allowing more visibility into which components rendered which markup. Defaults to "false". Component render
    260         * tracing may be
    261         * enabled per-request by the presence of a request parameter "t:component-trace" with a value of "true".
    262         *
    263         * @since 5.2.5
    264         */
    265        public static final String COMPONENT_RENDER_TRACING_ENABLED = "tapestry.component-render-tracing-enabled";
    266
    267        /**
    268         * The hostname that application should use when constructing an absolute URL. The default is "", i.e. an empty
    269         * string,
    270         * in which case system will use request.getServerName(). Not the same as environment variable HOSTNAME, but you can
    271         * also
    272         * contribute "$HOSTNAME" as the value to make it the same as the environment variable HOSTNAME.
    273         *
    274         * @since 5.3
    275         */
    276        public static final String HOSTNAME = "tapestry.hostname";
    277
    278        /**
    279         * The hostport that application should use when constructing an absolute URL. The default is "0", i.e. use the port
    280         * value from
    281         * the request.
    282         *
    283         * @since 5.3
    284         */
    285        public static final String HOSTPORT = "tapestry.hostport";
    286
    287        /**
    288         * The secure (https) hostport that application should use when constructing an absolute URL. The default is "0",
    289         * i.e. use
    290         * the value from the request.
    291         *
    292         * @since 5.3
    293         */
    294        public static final String HOSTPORT_SECURE = "tapestry.hostport-secure";
    295
    296        /**
    297         * If "true", then resources (individually or when aggregated into stacks) will be minimized via the
    298         * {@link ResourceMinimizer} service. If "false", then minification is disabled. Tracks production mode
    299         * (minification is normally disabled in development mode).
    300         * <p/>
    301         * Note that Tapestry's default implementation of {@link ResourceMinimizer} does nothing; minification is provided
    302         * by add-on libraries.
    303         *
    304         * @since 5.3
    305         */
    306        public static final String MINIFICATION_ENABLED = "tapestry.enable-minification";
    307
    308        /**
    309         * If "true" then at the end of each request the
    310         * {@link org.apache.tapestry5.services.SessionPersistedObjectAnalyzer} will be called on each session persisted
    311         * object that was accessed during the request.
    312         * <p/>
    313         * This is provided as a performance enhancement for servers that do not use clustered sessions.
    314         * <p/>
    315         * The default is {@code true}, to preserve 5.2 behavior. For non-clustered applications (the majority), this value should be
    316         * overridden to {@code false}. A future release of Tapestry may change the default.
    317         *
    318         * @since 5.3
    319         */
    320        public static final String CLUSTERED_SESSIONS = "tapestry.clustered-sessions";
    321
    322        /**
    323         * The fix for <a href="https://issues.apache.org/jira/browse/TAP5-1596">TAP5-1596</a> means that component ids referenced
    324         * by event handler methods (either the naming convention, or the {@link org.apache.tapestry5.annotations.OnEvent} annotation)
    325         * can cause a page load error if there is no matching component in the component's template. Although this is correct behavior,
    326         * it can make the upgrade from 5.2 to 5.3 difficult if an existing app had some "left over" event handler methods. Changing
    327         * this symbol to {@code false} is a temporary approach to resolving this problem.
    328         * <p/>
    329         * This symbol will be <em>ignored</em> in release 5.4 and removed in 5.5.
    330         *
    331         * @since 5.3
    332         * @deprecated Deprecated in 5.3, a future release will always enforce that component ids referenced by event handler methods actually exist.
    333         */
    334        @Deprecated
    335        public static final String UNKNOWN_COMPONENT_ID_CHECK_ENABLED = "tapestry.compatibility.unknown-component-id-check-enabled";
    336
    337        /**
    338         * The name of a folder in which the Tapestry application executes. Prior to 5.3, a Tapestry application always responded to all
    339         * 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
    340         * 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
    341         * from Tapestry 4 or some other framework, to Tapestry 5).
    342         * <p>Effectively, if this symbol is set to a value, that folder name will be placed after the context path
    343         * (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
    344         * only be in invoked by the servlet container for requests inside the virtual {@code app} folder.
    345         * <p/>
    346         * 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.
    347         * <p/>
    348         * The default value is the empty string, which preserves Tapestry 5.2 behavior (and continues to be appropriate for most applications).
    349         * <p/>
    350         * Note that while Tapestry is case-insensitive, the servlet container is not, so the configured value must exactly match
    351         * the folder name inside the {@code <url-parameter>} value, including case.
    352         *
    353         * @since 5.3
    354         */
    355        public static final String APPLICATION_FOLDER = "tapestry.application-folder";
    356
    357        /**
    358         * Boolean value to indicate if every {@link  org.apache.tapestry5.Asset2} should be fully qualified or not.
    359         * Default to <code>false</code> meaning no Asset URL will be fully qualified.
    360         * @since 5.3
    361         */
    362        public static final String ASSET_URL_FULL_QUALIFIED = "tapestry.asset-url-fully-qualified";
    363
    364        /**
    365         * Prefix to be used for all asset paths
    366         */
    367        public static final String ASSET_PATH_PREFIX = "tapestry.asset-path-prefix";
    368
    369        /**
    370         * A passphrase used as the basis of hash-based message authentication (HMAC) for any object stream data stored on
    371         * the client.  The default phrase is the empty string, which will result in a logged runtime <em>error</em>.
    372         * You should configure this to a reasonable value (longer is better) and ensure that all servers in your cluster
    373         * share the same value (configuring this in code, rather than the command line, is preferred).
    374         *
    375         * @see org.apache.tapestry5.services.ClientDataEncoder
    376         * @since 5.3.6
    377         */
    378        public static final String HMAC_PASSPHRASE = "tapestry.hmac-passphrase";
    379    }