    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 java.util.Arrays;
    016import java.util.List;
    017
    018import org.apache.tapestry5.commons.Resource;
    019
    020/**
    021 * Used to define a <a href="http://requirejs.org/docs/api.html#config-shim">module shim</a>, used to adapt non-AMD JavaScript libraries
    022 * to operate like proper modules.  This information is used to build up a list of dependencies for the contributed JavaScript module,
    023 * and to identify the resource to be streamed to the client.
    024 *
    025 * Instances of this class are contributed to the {@link ModuleManager} service;  the contribution key is the module name
    026 * (typically, a single word).
    027 *
    028 * In some cases, an instance may be created and contributed to override a default module; if the module has no dependencies,
    029 * exports, or initExpression (that is, if it is a proper AMD module, where such dependencies are provided inside
    030 * the module itself), then no client-side shim configuration will be written for the module, but requests for the
    031 * module will be satisfied by the resource.'
    032 *
    033 * @since 5.4
    034 * @see AMDWrapper
    035 */
    036public final class JavaScriptModuleConfiguration
    037{
    038    /**
    039     * The resource for this shim module.
    040     */
    041    public final Resource resource;
    042
    043    /**
    044     * The names of other shim modules that should be loaded before this shim module.
    045     */
    046    private List<String> dependencies;
    047
    048    /**
    049     * Optional (but desirable) value exported by the shim module.
    050     */
    051    private String exports;
    052
    053    private String initExpression;
    054
    055    private boolean needsConfiguration;
    056
    057    public JavaScriptModuleConfiguration(Resource resource)
    058    {
    059        assert resource != null;
    060
    061        this.resource = resource;
    062    }
    063
    064    /**
    065     * A list of other module names the shim depends on.
    066     *
    067     * @param moduleNames
    068     * @return this JavaScriptModuleConfiguration for further configuration
    069     */
    070    public JavaScriptModuleConfiguration dependsOn(String... moduleNames)
    071    {
    072        assert moduleNames.length > 0;
    073
    074        dependencies = Arrays.asList(moduleNames);
    075
    076        needsConfiguration = true;
    077
    078        return this;
    079    }
    080
    081    public List<String> getDependencies()
    082    {
    083        return dependencies;
    084    }
    085
    086    /**
    087     * The name of a global variable exported by the module. This will be the value injected into
    088     * modules that depend on the shim.
    089     *
    090     * @return this JavaScriptModuleConfiguration for further configuration
    091     */
    092    public JavaScriptModuleConfiguration exports(String exports)
    093    {
    094        assert exports != null;
    095
    096        this.exports = exports;
    097
    098        needsConfiguration = true;
    099
    100        return this;
    101    }
    102
    103    public String getExports()
    104    {
    105        return exports;
    106    }
    107
    108    /**
    109     * Used as an alternative to {@linkplain #exports(String)}, this allows a short expression to be specified; the
    110     * expression is used to initialize, clean up, and (usually) return the module's export value. For Underscore, this
    111     * would be "_.noConflict()".  If the expression returns null, then the exports value is used.
    112     *
    113     * In RequireJS 2.1.1 (the version shipped with Tapestry, currently), an init function is not invoked unless
    114     * the shim also defines an exports. See <a href="https://github.com/jrburke/requirejs/issues/517">RequireJS issue 517</a>.
    115     * At this time, you should specify {@link #exports} even if you provide a {@link #initializeWith(String)}}.
    116     *
    117     * @param expression
    118     *         initialization expression
    119     * @return this JavaScriptModuleConfiguration, for further configuration
    120     */
    121    public JavaScriptModuleConfiguration initializeWith(String expression)
    122    {
    123        assert expression != null;
    124
    125        this.initExpression = expression;
    126
    127        needsConfiguration = true;
    128
    129        return this;
    130    }
    131
    132    public String getInitExpression()
    133    {
    134        return initExpression;
    135    }
    136
    137    /**
    138     * Returns true if the module contains any additional configuration beyond its {@link Resource}.
    139     */
    140    public boolean getNeedsConfiguration()
    141    {
    142        return needsConfiguration;
    143    }
    144}