    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}