    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}