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.services.javascript;
014
015import org.apache.tapestry5.Asset;
016import org.apache.tapestry5.SymbolConstants;
017import org.apache.tapestry5.ioc.services.ThreadLocale;
018import org.apache.tapestry5.services.AssetSource;
019
020import java.util.List;
021
022/**
023 * A high level description of a group of related JavaScript libraries and stylesheets. The built-in "core"
024 * stack is used to define the core JavaScript libraries needed by Tapestry (though this has been largely replaced by
025 * JavaScript modules in Tapestry 5.4,
026 * and the may be no libraries in the core stack by Tapestry 5.5). Other component libraries may
027 * define additional stacks for related sets of resources, for example, to bundle together some portion
028 * of the ExtJS or YUI libraries.
029 *
030 * The JavaScript assets of a stack may (when {@linkplain SymbolConstants#COMBINE_SCRIPTS enabled}) be exposed to the
031 * client as a single URL (identifying the stack by name). The individual JavaScript  assets are combined into a single virtual
032 * asset, which is then streamed to the client. The individual JavaScript libraries, or the combined virtual library,
033 * may be {@linkplain SymbolConstants#MINIFICATION_ENABLED minimized} and the content (both compressed and
034 * uncompressed) cached.
035 *
036 * Implementations may need to inject the {@link ThreadLocale} service in order to determine the current locale (if any
037 * of the JavaScript library or stylesheet assets are localized). They will generally need to inject the
038 * {@link AssetSource} service as well.
039 *
040 * The {@link ExtensibleJavaScriptStack} is the best way to create new stacks.
041 *
042 * @see ThreadLocale
043 * @see org.apache.tapestry5.services.javascript.ExtensibleJavaScriptStack
044 * @since 5.2.0
045 */
046public interface JavaScriptStack
047{
048    /**
049     * Returns a list of JavaScriptStack names that this stack depends on. Each stack will be processed before
050     * the current stack (thus a dependency stack's libraries, stylesheets and initialization is emitted before
051     * the dependent stack).
052     */
053    List<String> getStacks();
054
055    /**
056     * Returns a list of <em>localized</em> assets for JavaScript libraries that form the stack.
057     */
058    List<Asset> getJavaScriptLibraries();
059
060    /**
061     * Returns a list of <em>localized</em> links for stylesheets that form the stack.
062     */
063    List<StylesheetLink> getStylesheets();
064
065    /**
066     * Returns a list of modules to include with the stack, when aggregating the stack's JavaScript.
067     * It is still necessary to explicitly {@linkplain org.apache.tapestry5.services.javascript.JavaScriptSupport#require(String) require}
068     * such modules.
069     *
070     * @see ModuleManager
071     * @see org.apache.tapestry5.SymbolConstants#COMBINE_SCRIPTS
072     * @since 5.4
073     */
074    List<String> getModules();
075
076    /**
077     * Identifies how to aggregate JavaScript within the stack.
078     * The default is {@link org.apache.tapestry5.services.javascript.JavaScriptAggregationStrategy#COMBINE_AND_MINIMIZE}.
079     *
080     * @since 5.4
081     */
082    JavaScriptAggregationStrategy getJavaScriptAggregationStrategy();
083
084    /**
085     * Returns static JavaScript initialization for the stack. This block of JavaScript code will be added to the
086     * page that imports the stack. The code executes outside of any other function (i.e., the code is not deferred
087     * until the DOM is loaded). As with the other methods, if localization is a factor, the result of this method
088     * should be localized.
089     *
090     * @deprecated Deprecated in Tapestry 5.4; may be removed in a future release. Implementations
091     * may return null.
092     */
093    String getInitialization();
094}