// Copyright (c) 2014 The Chromium Embedded Framework Authors. All rights
// reserved. Use of this source code is governed by a BSD-style license that
// can be found in the LICENSE file.

package org.cef.browser;

import org.cef.handler.CefMessageRouterHandler;

/**
 * The below classes implement support for routing aynchronous messages between
 * JavaScript running in the renderer process and C++ running in the browser
 * process. An application interacts with the router by passing it data from
 * standard CEF C++ callbacks (OnBeforeBrowse, OnProcessMessageRecieved,
 * OnContextCreated, etc). The renderer-side router supports generic JavaScript
 * callback registration and execution while the browser-side router supports
 * application-specific logic via one or more application-provided Handler
 * instances.
 *
 * The renderer-side router implementation exposes a query function and a cancel
 * function via the JavaScript 'window' object:
 *
 *    // Create and send a new query.
 *    var request_id = window.cefQuery({
 *        request: 'my_request',
 *        persistent: false,
 *        onSuccess: function(response) {},
 *        onFailure: function(error_code, error_message) {}
 *    });
 *
 *    // Optionally cancel the query.
 *    window.cefQueryCancel(request_id);
 *
 * When |window.cefQuery| is executed the request is sent asynchronously to one
 * or more C++ Handler objects registered in the browser process. Each C++
 * Handler can choose to either handle or ignore the query in the
 * Handler::OnQuery callback. If a Handler chooses to handle the query then it
 * should execute Callback::Success when a response is available or
 * Callback::Failure if an error occurs. This will result in asynchronous
 * execution of the associated JavaScript callback in the renderer process. Any
 * queries unhandled by C++ code in the browser process will be automatically
 * canceled and the associated JavaScript onFailure callback will be executed
 * with an error code of -1.
 *
 * Queries can be either persistent or non-persistent. If the query is
 * persistent than the callbacks will remain registered until one of the
 * following conditions are met:
 *
 * A. The query is canceled in JavaScript using the |window.cefQueryCancel|
 *    function.
 * B. The query is canceled in C++ code using the Callback::Failure function.
 * C. The context associated with the query is released due to browser
 *    destruction, navigation or renderer process termination.
 *
 * If the query is non-persistent then the registration will be removed after
 * the JavaScript callback is executed a single time. If a query is canceled for
 * a reason other than Callback::Failure being executed then the associated
 * Handler's OnQueryCanceled method will be called.
 *
 * Some possible usage patterns include:
 *
 * One-time Request. Use a non-persistent query to send a JavaScript request.
 *    The Handler evaluates the request and returns the response. The query is
 *    then discarded.
 *
 * Broadcast. Use a persistent query to register as a JavaScript broadcast
 *    receiver. The Handler keeps track of all registered Callbacks and executes
 *    them sequentially to deliver the broadcast message.
 *
 * Subscription. Use a persistent query to register as a JavaScript subscription
 *    receiver. The Handler initiates the subscription feed on the first request
 *    and delivers responses to all registered subscribers as they become
 *    available. The Handler cancels the subscription feed when there are no
 *    longer any registered JavaScript receivers.
 *
 * Message routing occurs on a per-browser and per-context basis. Consequently,
 * additional application logic can be applied by restricting which browser or
 * context instances are passed into the router. If you choose to use this
 * approach do so cautiously. In order for the router to function correctly any
 * browser or context instance passed into a single router callback must then
 * be passed into all router callbacks.
 *
 * There is generally no need to have multiple renderer-side routers unless you
 * wish to have multiple bindings with different JavaScript function names. It
 * can be useful to have multiple browser-side routers with different client-
 * provided Handler instances when implementing different behaviors on a per-
 * browser basis.
 *
 * This implementation places no formatting restrictions on payload content.
 * An application may choose to exchange anything from simple formatted
 * strings to serialized XML or JSON data.
 *
 *
 * EXAMPLE USAGE
 *
 * 1. Define the router configuration. You can optionally specify settings
 *    like the JavaScript function names. The configuration must be the same in
 *    both the browser and renderer processes. If using multiple routers in the
 *    same application make sure to specify unique function names for each
 *    router configuration.
 *
 *    // Example config object showing the default values.
 *    CefMessageRouterConfig config = new CefMessageRouterConfig();
 *    config.jsQueryFunction = "cefQuery";
 *    config.jsCancelFunction = "cefQueryCancel";
 *
 * 2. Create an instance of CefMessageRouter in the browser process.
 *
 *    messageRouter_ = CefMessageRouter.create(config);
 *
 * 3. Register one or more Handlers. The Handler instances must either outlive
 *    the router or be removed from the router before they're deleted.
 *
 *    messageRouter_.addHandler(myHandler);
 *
 * 4. Add your message router to all CefClient instances you want to get your
 *    JavaScript code be handled.
 *
 *    myClient.addMessageRouter(messageRouter_);
 *
 * 4. Execute the query function from JavaScript code.
 *
 *    window.cefQuery({request: 'my_request',
 *                     persistent: false,
 *                     onSuccess: function(response) { print(response); },
 *                     onFailure: function(error_code, error_message) {} });
 *
 * 5. Handle the query in your CefMessageRouterHandler.onQuery implementation
 *    and execute the appropriate callback either immediately or asynchronously.
 *
 *    public boolean onQuery(CefBrowser browser,
 *                           long query_id,
 *                           String request,
 *                           boolean persistent,
 *                           CefQueryCallback callback) {
 *      if (request.indexOf("my_request") == 0) {
 *        callback.success("my_response");
 *        return true;
 *      }
 *      return false;  // Not handled.
 *    }
 *
 * 6. Notice that the success callback is executed in JavaScript.
 */
public abstract class CefMessageRouter {
    private CefMessageRouterConfig routerConfig_ = null;

    /**
     * Used to configure the query router. If using multiple router pairs make
     * sure to choose values that do not conflict.
     */
    public static class CefMessageRouterConfig {
        /**
         * Name of the JavaScript function that will be added to the 'window' object
         * for sending a query. The default value is "cefQuery".
         */
        public String jsQueryFunction;

        /**
         * Name of the JavaScript function that will be added to the 'window' object
         * for canceling a pending query. The default value is "cefQueryCancel".
         */
        public String jsCancelFunction;

        public CefMessageRouterConfig() {
            this("cefQuery", "cefQueryCancel");
        }

        public CefMessageRouterConfig(String queryFunction, String cancelFunction) {
            jsQueryFunction = queryFunction;
            jsCancelFunction = cancelFunction;
        }
    }

    // This CTOR can't be called directly. Call method create() instead.
    CefMessageRouter() {}

    @Override
    protected void finalize() throws Throwable {
        dispose();
        super.finalize();
    }

    /**
     * Create a new router with the default configuration. The addHandler() method should be called
     * to add a handler.
     */
    public static final CefMessageRouter create() {
        return CefMessageRouter.create(null, null);
    }

    /**
     * Create a new router with the specified configuration. The addHandler() method should be
     * called to add a handler.
     */
    public static final CefMessageRouter create(CefMessageRouterConfig config) {
        return CefMessageRouter.create(config, null);
    }

    /**
     * Create a new router with the specified handler and default configuration.
     */
    public static final CefMessageRouter create(CefMessageRouterHandler handler) {
        return CefMessageRouter.create(null, handler);
    }

    /**
     * Create a new router with the specified handler and configuration.
     */
    public static final CefMessageRouter create(
            CefMessageRouterConfig config, CefMessageRouterHandler handler) {
        CefMessageRouter router = CefMessageRouter_N.createNative(config);
        if (router != null && handler != null) router.addHandler(handler, true);
        return router;
    }

    /**
     * Must be called if the CefMessageRouter instance isn't used any more.
     */
    public abstract void dispose();

    // Called from native code during handling of createNative().
    void setMessageRouterConfig(CefMessageRouterConfig config) {
        routerConfig_ = config;
    }

    // Called from native code during handling of CefClientHandler.[add|remove]MessageRouter().
    public final CefMessageRouterConfig getMessageRouterConfig() {
        return routerConfig_;
    }

    /**
     * Add a new query handler.
     *
     * @param handler The handler to be added.
     * @param first If true the handler will be added as the first handler, otherwise it will be
     *         added as the last handler.
     * @return True if the handler is added successfully.
     */
    public abstract boolean addHandler(CefMessageRouterHandler handler, boolean first);

    /**
     * Remove an existing query handler. Any pending queries associated with the handler will be
     * canceled. onQueryCanceled will be called and the associated JavaScript onFailure callback
     * will be executed with an error code of -1.
     *
     * @param handler The handler to be removed.
     * @return True if the handler is removed successfully.
     */
    public abstract boolean removeHandler(CefMessageRouterHandler handler);

    /**
     * Cancel all pending queries associated with either |browser| or |handler|. If both |browser|
     * and |handler| are NULL all pending queries will be canceled. onQueryCanceled will be called
     * and the associated JavaScript onFailure callback will be executed in all cases with an error
     * code of -1.
     *
     * @param browser The associated browser, or null.
     * @param handler The associated handler, or null.
     */
    public abstract void cancelPending(CefBrowser browser, CefMessageRouterHandler handler);
}