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