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.commons.Resource;
016import org.apache.tapestry5.dom.Element;
017import org.apache.tapestry5.ioc.annotations.UsesMappedConfiguration;
018
019import java.util.List;
020
021/**
022 * Responsible for managing access to the JavaScript modules.
023 *
024 * The configuration of the service allows overrides of the default search path; the configuration keys
025 * are module names, and the configuration values are the {@link JavaScriptModuleConfiguration} definitions for those module names.
026 * This is primarily used to wrap non-AMD compliant libraries for use with RequireJS (via contributed {@link JavaScriptModuleConfiguration}s).
027 *
028 * @since 5.4
029 * @see ModuleConfigurationCallback
030 * @see AMDWrapper
031 */
032@UsesMappedConfiguration(JavaScriptModuleConfiguration.class)
033public interface ModuleManager
034{
035    /**
036     * Invoked by the internal {@link org.apache.tapestry5.internal.services.DocumentLinker} service to write the configuration
037     * for the module system into the page.
038     *
039     * @param body
040     *         {@code <body>} element of the page, to which new {@code <script>} element(s) will be added.
041     * @param moduleConfigurationCallbacks
042     *         a list of {@link org.apache.tapestry5.services.javascript.ModuleConfigurationCallback}s, which
043     *         is used to customize the configuration before it is written.
044     */
045    void writeConfiguration(Element body,
046                            List<ModuleConfigurationCallback> moduleConfigurationCallbacks);
047
048    /**
049     * Invoked by the internal {@link org.apache.tapestry5.internal.services.DocumentLinker} service to write the initializations
050     * (as per {@link JavaScriptSupport#require(String)} into the page; this occurs after the module infrastructure
051     * has been written into the page, along with the core libraries.
052     *
053     * @param body
054     *         {@code <body>} element of the page, to which new {@code <script>} element(s) will be added.
055     * @param libraryURLs
056     *         additional libraries that should be dynamically loaded before evaluating the inits
057     * @param inits
058     *         specify initialization on the page, based on loading modules, extacting functions from modules, and invoking those functions
059     */
060    void writeInitialization(Element body, List<String> libraryURLs, List<?> inits);
061
062    /**
063     * Given a module name (which may be a path of names separated by slashes), locates the corresponding {@link Resource}.
064     * First checks for {@linkplain JavaScriptModuleConfiguration contributed shim modules}, then searches for possible matches among the
065     * {@linkplain org.apache.tapestry5.services.ComponentClassResolver#getLibraryNames() defined library names}.  As a special
066     * case, the folder name "app" is mapped to the application's package.
067     *
068     * @param moduleName
069     *         name of module to locate
070     * @return corresponding resource, or null if not found
071     */
072    Resource findResourceForModule(String moduleName);
073
074}