001    // Copyright 2010 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.services.javascript;
016    
017    import java.util.List;
018    
019    import org.apache.tapestry5.Asset;
020    import org.apache.tapestry5.SymbolConstants;
021    import org.apache.tapestry5.ioc.services.ThreadLocale;
022    import org.apache.tapestry5.services.AssetSource;
023    
024    /**
025     * A high level description of a group of related JavaScript libraries and stylesheets. The built-in "core"
026     * stack is used to define the core JavaScript libraries needed by Tapestry (currently, this includes
027     * Prototype and Scriptaculous, as well as Tapestry-specific libraries). Other component libraries may
028     * define additional stacks for related sets of resources, for example, to bundle together some portion
029     * of the ExtJS or YUI libraries.
030     * <p>
031     * A JavaScript assets of a stack may (when {@linkplain SymbolConstants#COMBINE_SCRIPTS enabled}) be exposed to the
032     * client as a single URL (identifying the stack by name). The individual assets are combined into a single virtual
033     * asset, which is then streamed to the client.
034     * <p>
035     * Implementations may need to inject the {@link ThreadLocale} service in order to determine the current locale (if any
036     * of the JavaScript library or stylesheet assets are localized). They will generally need to inject the
037     * {@link AssetSource} service as well.
038     * 
039     * @since 5.2.0
040     * @see ThreadLocale
041     */
042    public interface JavaScriptStack
043    {
044        /**
045         * Returns a list of JavaScriptStack names that this stack depends on. Each stack will be processed before
046         * the current stack (thus a dependency stack's libraries, stylesheets and initialization is emitted before
047         * the dependent stack).
048         */
049        List<String> getStacks();
050    
051        /**
052         * Returns a list of <em>localized</em> assets for JavaScript libraries that form the stack.
053         */
054        List<Asset> getJavaScriptLibraries();
055    
056        /**
057         * Returns a list of <em>localized</em> links for stylesheets that form the stack.
058         */
059        List<StylesheetLink> getStylesheets();
060    
061        /**
062         * Returns static JavaScript initialization for the stack. This block of JavaScript code will be added to the
063         * page that imports the stack. The code executes outside of any other function (i.e., the code is not deferred
064         * until the DOM is loaded). As with the other methods, if localization is a factor, the result of this method
065         * should be localized.
066         */
067        String getInitialization();
068    }