/*
 * Copyright 2014 Red Hat, Inc.
 *
 *  All rights reserved. This program and the accompanying materials
 *  are made available under the terms of the Eclipse Public License v1.0
 *  and Apache License v2.0 which accompanies this distribution.
 *
 *  The Eclipse Public License is available at
 *  http://www.eclipse.org/legal/epl-v10.html
 *
 *  The Apache License v2.0 is available at
 *  http://www.opensource.org/licenses/apache2.0.php
 *
 *  You may elect to redistribute this code under either of these licenses.
 */

package io.vertx.ext.web.handler;

import io.vertx.codegen.annotations.GenIgnore;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.AsyncResult;
import io.vertx.core.Future;
import io.vertx.core.Handler;
import io.vertx.core.Promise;
import io.vertx.ext.auth.authentication.Credentials;
import io.vertx.ext.web.RoutingContext;

Base interface for auth handlers.

An auth handler allows your application to provide authentication/authorization support.
 Auth handler requires a SessionHandler to be on the routing chain before it. 
Author:
Tim Fox, Paulo Lopes/**
 * Base interface for auth handlers.
 * <p>
 * An auth handler allows your application to provide authentication/authorization support.
 * <p>
 * Auth handler requires a {@link SessionHandler} to be on the routing chain before it.
 *
 * @author <a href="http://tfox.org">Tim Fox</a>
 * @author <a href="mailto:plopes@redhat.com">Paulo Lopes</a>
 */
@VertxGen(concrete = false)
public interface AuthenticationHandler extends Handler<RoutingContext> {

  
Parses the credentials from the request into a JsonObject. The implementation should
be able to extract the required info for the auth provider in the format the provider
expects.
Params:
context – the routing context
handler – the handler to be called once the information is available./**
   * Parses the credentials from the request into a JsonObject. The implementation should
   * be able to extract the required info for the auth provider in the format the provider
   * expects.
   *
   * @param context the routing context
   * @param handler the handler to be called once the information is available.
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  void parseCredentials(RoutingContext context, Handler<AsyncResult<Credentials>> handler);

  
Params:
context – the routing context
See Also:
parseCredentials.parseCredentials(RoutingContext, Handler)
Returns:
Future json/**
   * @see AuthenticationHandler#parseCredentials(RoutingContext, Handler)
   * @param context the routing context
   * @return Future json
   */
  @GenIgnore(GenIgnore.PERMITTED_TYPE)
  default Future<Credentials> parseCredentials(RoutingContext context) {
    Promise<Credentials> promise = Promise.promise();
    parseCredentials(context, promise);
    return promise.future();
  }

  
Returns
Params:
context – 
Returns:
/**
   * Returns
   * @param context
   * @return
   */
  default String authenticateHeader(RoutingContext context) {
    return null;
  }

  
This method is called to perform any post authentication tasks, such as redirects.
Overrides must call context.next() on success.
Params:
ctx – the routing context/**
   * This method is called to perform any post authentication tasks, such as redirects.
   * Overrides must call context.next() on success.
   *
   * @param ctx the routing context
   */
  default void postAuthentication(RoutingContext ctx) {
    ctx.next();
  }

}