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
015/**
016 * Provided by {@link JavaScriptSupport#require(String)} to allow additional, optional, details of the module-based page initialization
017 * to be configured.
018 *
019 * @since 5.4
020 */
021public interface Initialization
022{
023
024    /**
025     * Specifies the function to invoke.  If this method is not invoked, then the module is expected to export
026     * just a single function (which may, or may not, take {@linkplain #with(Object...) parameters}).
027     *
028     * @param functionName
029     *         name of a function exported by the module.
030     * @return this Initialization, for further configuration
031     */
032    Initialization invoke(String functionName);
033
034    /**
035     * Changes the initialization priority of the initialization from its default, {@link InitializationPriority#NORMAL}.
036     *
037     * Note: it is possible that this method may be removed before release 5.4 is final.
038     *
039     * @param priority
040     *         new priority
041     * @return this Initialization, for further configuration
042     */
043    Initialization priority(InitializationPriority priority);
044
045    /**
046     * Specifies the arguments to be passed to the function. Often, just a single {@link org.apache.tapestry5.json.JSONObject}
047     * is passed. When multiple Initializations exist with the same function name (or no function name), and no arguments,
048     * they are coalesced into a single Initialization: it is assumed that an initialization with no parameters needs to
049     * only be invoked once.
050     *
051     * @param arguments
052     *         any number of values. Each value may be one of: null, String, Boolean, Number,
053     *         {@link org.apache.tapestry5.json.JSONObject}, {@link org.apache.tapestry5.json.JSONArray}, or
054     *         {@link org.apache.tapestry5.json.JSONLiteral}.
055     */
056    void with(Object... arguments);
057}