/**
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 * <p>
 * http://www.apache.org/licenses/LICENSE-2.0
 * <p>
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.impala.hooks;

/**
 * {@link QueryEventHook} is the interface for implementations that
 * can hook into supported events in Impala query execution.
 */
public interface QueryEventHook {
  /**
   * Hook method invoked when the Impala daemon starts up.
   * <p>
   * This method will block completion of daemon startup, so you should
   * execute any long-running actions asynchronously.
   * </p>
   * <h3>Error-Handling</h3>
   * <p>
   * Any {@link Exception} thrown from this method will effectively fail
   * Impala startup with an error. Implementations should handle all
   * exceptions as gracefully as they can, even if the end result is to
   * throw them.
   * </p>
   */
  void onImpalaStartup();

  /**
   * Hook method invoked asynchronously when a (qualifying) Impala query
   * has executed, but before it has returned.
   * <p>
   * This method will not block the invoking or subsequent queries,
   * but may block future hook invocations if it runs for too long
   * </p>
   * <h3>Error-Handling</h3>
   * <p>
   * Any {@link Throwable} thrown from this method will only be caught
   * and logged and will not affect the result of any query.  Hook implementations
   * should make a best-effort to handle their own exceptions.
   * </p>
   * <h3>Important:</h3>
   * <p>
   * This hook is actually invoked when the query is <i>unregistered</i>,
   * which may happen a long time after the query has executed.
   * e.g. the following sequence is possible:
   * <ol>
   *  <li>User executes query from Hue.
   *  <li>User goes home for weekend, leaving Hue tab open in browser
   *  <li>If we're lucky, the session timeout expires after some amount of idle time.
   *  <li>The query gets unregistered, lineage record gets logged
   * </ol>
   * </p>
   * <h3>Service Guarantees</h3>
   *
   * Impala makes the following guarantees about how this method is executed
   * with respect to other implementations that may be registered:
   *
   * <h4>Hooks are executed asynchronously</h4>
   *
   * All hook execution happens asynchronously of the query that triggered
   * them.  Hooks may still be executing after the query response has returned
   * to the caller.  Additionally, hooks may execute concurrently if the
   * hook executor thread size is configured appropriately.
   *
   * <h4>Hook Invocation is in Configuration Order</h4>
   *
   * The <i>submission</i> of the hook execution tasks occurs in the order
   * that the hooks were defined in configuration.  This generally means that
   * hooks will <i>start</i> executing in order, but there are no guarantees
   * about finishing order.
   * <p>
   * For example, if configured with {@code query_event_hook_classes=hook1,hook2,hook3},
   * then hook1 will start before hook2, and hook2 will start before hook3.
   * If you need to guarantee that hook1 <i>completes</i> before hook2 starts, then
   * you should specify {@code query_event_hook_nthreads=1} for serial hook
   * execution.
   * </p>
   *
   * <h4>Hook Execution Blocks</h4>
   *
   * A hook will block the thread it executes on until it completes.  If a hook hangs,
   * then the thread also hangs.  Impala (currently) will not check for hanging hooks to
   * take any action.  This means that if you have {@code query_event_hook_nthreads}
   * less than the number of hooks, then 1 hook may effectively block others from
   * executing.
   *
   * <h4>Hook Exceptions are non-fatal</h4>
   *
   * Any exception thrown from this hook method will be logged and ignored.  Therefore,
   * an exception in 1 hook will not affect another hook (when no shared resources are
   * involved).
   *
   * <h4>Hook Execution may end abruptly at Impala shutdown</h4>
   *
   * If a hook is still executing when Impala is shutdown, there are no guarantees
   * that it will complete execution before being killed.
   *
   *
   * @param context object containing the post execution context
   *                of the query
   */
  void onQueryComplete(QueryCompleteContext context);
}