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.
012package org.apache.tapestry5.http;
013
014import org.apache.tapestry5.http.services.CorsHandler;
015import org.apache.tapestry5.http.services.CorsHandlerHelper;
016import org.apache.tapestry5.http.services.CorsHttpServletRequestFilter;
017
018/**
019 * Class defining constants for Tapestry HTTP symbols.
020 */
021final public class TapestryHttpSymbolConstants {
022
023    /**
024     * The hostname that application should use when constructing an absolute URL. The default is "", i.e. an empty
025     * string,
026     * in which case system will use request.getServerName(). Not the same as environment variable HOSTNAME, but you can
027     * also
028     * contribute "$HOSTNAME" as the value to make it the same as the environment variable HOSTNAME.
029     *
030     * @since 5.3
031     */
032    public static final String HOSTNAME = "tapestry.hostname";
033    /**
034     * The hostport that application should use when constructing an absolute URL. The default is "0", i.e. use the port
035     * value from
036     * the request.
037     *
038     * @since 5.3
039     */
040    public static final String HOSTPORT = "tapestry.hostport";
041    /**
042     * The secure (https) hostport that application should use when constructing an absolute URL. The default is "0",
043     * i.e. use
044     * the value from the request.
045     * This is an alias to {@link TapestryHttpSymbolConstants#HOSTPORT_SECURE}.
046     *
047     * @since 5.3
048     */
049    public static final String HOSTPORT_SECURE = "tapestry.hostport-secure";
050    /**
051     * If "true" then at the end of each request the
052     * {@link org.apache.tapestry5.http.services.SessionPersistedObjectAnalyzer} will be called on each session persisted
053     * object that was accessed during the request.
054     *
055     * This is provided as a performance enhancement for servers that do not use clustered sessions.
056     *
057     * The default is {@code true}, to preserve 5.2 behavior. For non-clustered applications (the majority), this value should be
058     * overridden to {@code false}. A future release of Tapestry may change the default.
059     *
060     * @since 5.3
061     */
062    public static final String CLUSTERED_SESSIONS = "tapestry.clustered-sessions";
063    /**
064     * If true (the default), then Tapestry will apply locking semantics around access to the {@link javax.servlet.http.HttpSession}.
065     * Reading attribute names occurs with a shared read lock; getting or setting an attribute upgrades to an exclusive write lock.
066     * This can tend to serialize threads when a number of simultaneous (Ajax) requests from the client arrive ... however,
067     * many implementations of HttpSession are not thread safe, and often mutable objects are stored in the session and shared
068     * between threads. Leaving this on the default will yield a more robust application; setting it to false may speed
069     * up processing for more Ajax intensive applications (but care should then be given to ensuring that objects shared inside
070     * the session are themselves immutable or thread-safe).
071     *
072     * @since 5.4
073     */
074    public static final String SESSION_LOCKING_ENABLED = "tapestry.session-locking-enabled";
075    /**
076     * Version number of the application. Prior to 5.4, this version number was integrated into asset URLs. Starting
077     * with 5.4, a checksum of the individual asset's content is used instead, and this version number is only used
078     * for documentation purposes; it appears in the default exception report page, for example.
079     *
080     * The default value is "0.0.1".  In 5.3 and earlier, the default value was a random hexadecimal string.
081     *
082     * @since 5.1.0.0
083     */
084    public static final String APPLICATION_VERSION = "tapestry.application-version";
085    
086    /**
087     * Indicates whether Tapestry is running in production mode or developer mode. This affects a large
088     * number of Tapestry behaviors related to performance and security, including how exceptions are
089     * reported, whether far-future expire headers are emitted, whether JavaScript files may be combined,
090     * whether JSON is compressed, whether component field and parameter values are shadowed to instance
091     * variables (to assist with debugging), and more.
092     */
093    public static final String PRODUCTION_MODE = "tapestry.production-mode";
094    
095    /**
096     * The version number of the core Tapestry framework, or UNKNOWN if the version number is not available (which
097     * should only occur when developing Tapestry).
098     */
099    public static final String TAPESTRY_VERSION = "tapestry.version";
100    
101    /**
102     * Identifies the context path of the application, as determined from {@link javax.servlet.ServletContext#getContextPath()}.
103     * This is either a blank string or a string that starts with a slash but does not end with one.
104     *
105     * @since 5.4
106     */
107    public static final String CONTEXT_PATH = "tapestry.context-path";
108    /**
109     * A comma separated list of execution modes used to control how the application is initialized.
110     * Each modes can contribute a list (comma separated) of Module classes to be loaded during startup,
111     * the order in which they appear is preserved.
112     * The default value is: <code>production</code>.
113     */
114    public static final String EXECUTION_MODE = "tapestry.execution-mode";
115    /**
116     * The charset used when rendering page markup; the charset is also used as the request encoding when handling
117     * incoming requests. The default is "UTF-8".
118     */
119    public static final String CHARSET = "tapestry.charset";
120    /**
121     * Minimum output stream size, in bytes, before output is compressed using GZIP. Shorter streams are not compressed.
122     * Tapestry buffers this amount and switches to a GZIP output stream as needed. The default is "100".
123     *
124     * @see #GZIP_COMPRESSION_ENABLED
125     * @since 5.1.0.0
126     */
127    public static final String MIN_GZIP_SIZE = "tapestry.min-gzip-size";
128    /**
129     * If "true" (the default) then GZip compression is enabled for dynamic requests and for static assets. If you are
130     * using a server that handles GZip compression for you, or you don't want to use the extra processing power
131     * necessary to GZIP requests, then override this to "false".
132     *
133     * @see #MIN_GZIP_SIZE
134     * @see org.apache.tapestry5.http.services.ResponseCompressionAnalyzer
135     * @see org.apache.tapestry5.http.services.CompressionAnalyzer
136     * @since 5.1.0.0
137     */
138    public static final String GZIP_COMPRESSION_ENABLED = "tapestry.gzip-compression-enabled";
139    /**
140     * Defines whether the CORS (Cross-Origing Resource Sharing) support 
141     * should be enabled or not. Default value is "false". If you set this to "true",
142     * you should also set {@link #CORS_ALLOWED_ORIGINS}.
143     * @see CorsHandler
144     * @see CorsHttpServletRequestFilter
145     * @since 5.8.2
146     */
147    public static final String CORS_ENABLED = "tapestry.cors-enabled";
148
149    /**
150     * Comma-delimited of origins allowed for CORS. The special value "*" means allowing all origins.
151     * This is used by the default implementation of {@link CorsHandlerHelper#getAllowedOrigin(javax.servlet.http.HttpServletRequest)}.
152     * Default value is the empty string (i.e. no origins allowed and CORS actually disabled).
153     * @since 5.8.2
154     */
155    public static final String CORS_ALLOWED_ORIGINS = "tapestry.cors-allowed-origins";
156    
157    /**
158     * Boolean value defining whether the Access-Control-Allow-Credentials HTTP header
159     * should be set automatically in the response for CORS requests. Default value is
160     * <code>false</code>. This is used by the default implementation of {@link CorsHandlerHelper#configureCredentials(javax.servlet.http.HttpServletResponse)}.
161     * @since 5.8.2
162     */
163    public static final String CORS_ALLOW_CREDENTIALS = "tapestry.cors-allow-credentials";
164
165    /**
166     * Value to be used in the Access-Control-Allow-Methods in CORS preflight request responses.
167     * This is used by {@link CorsHandlerHelper#configureMethods(javax.servlet.http.HttpServletResponse)}.
168     * Default value is <code>GET,HEAD,PUT,PATCH,POST,DELETE</code>.
169     * @since 5.8.2
170     */
171    public static final String CORS_ALLOW_METHODS = "tapestry.cors-allow-methods";
172    
173    /**
174     * Value to be used in the Access-Control-Allow-Headers in CORS preflight request responses.
175     * This is used by {@link CorsHandlerHelper#configureAllowedHeaders(javax.servlet.http.HttpServletResponse, javax.servlet.http.HttpServletRequest)},
176     * which only sets the header if the value isn't empty.
177     * Default value is the empty string.
178     * @since 5.8.2
179     */
180    public static final String CORS_ALLOWED_HEADERS = "tapestry.cors-allowed-headers";
181    
182    /**
183     * Value to be used in the Access-Control-Expose-Headers in CORS preflight request responses.
184     * This is used by the default implementation of {@link CorsHandlerHelper#configureExposeHeaders(javax.servlet.http.HttpServletResponse)},
185     * which only sets the header if the value isn't empty.
186     * Default value is the empty string.
187     * @since 5.8.2
188     */
189    public static final String CORS_EXPOSE_HEADERS = "tapestry.cors-expose-headers";
190    
191    /**
192     * Value to be used in the Access-Control-Max-Age in responses to preflight CORS requests.
193     * This is used by {@link CorsHandlerHelper#configureMaxAge(javax.servlet.http.HttpServletResponse)},
194     * which only sets the header if the value isn't empty.
195     * Default value is the empty string.
196     * This is an alias for {@link TapestryHttpSymbolConstants#CORS_MAX_AGE}.
197     * @since 5.8.2
198     */
199    public static final String CORS_MAX_AGE = "tapestry.cors-max-age";
200
201}