/*
 * 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
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * 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.jackrabbit.core.api.security;

import java.security.Principal;
import java.util.Map;
import java.util.Set;

import javax.jcr.Credentials;
import javax.jcr.RepositoryException;
import javax.jcr.Session;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.login.FailedLoginException;
import javax.security.auth.login.LoginException;

import org.apache.jackrabbit.api.security.user.User;

/**
 * The <code>LoginModulePlugin</code> interface defines the API to be
 * implemented by a pluggable login module. Instances of this interface are
 * returned by the {@link LoginModulePluginFactory#create(Credentials)} method.
 *
 * @see DefaultLoginModulePlugin
 * @see LoginModulePluginFactory
 */
public interface LoginModulePlugin {

    /**
     * Returned by the {@link #impersonate(Principal, Credentials)} method if
     * impersonation should be handled by the <code>DefaultLoginModule</code>.
     */
    static final int IMPERSONATION_DEFAULT = 0;

    /**
     * Returned by the {@link #impersonate(Principal, Credentials)} method if
     * impersonation was handled by the login plugin and succeeded.
     */
    static final int IMPERSONATION_SUCCESS = 1;

    /**
     * Returned by the {@link #impersonate(Principal, Credentials)} method if
     * impersonation was handled by the login plugin and failed. The
     * <code>DefaultLoginModule</code> is not asked for impersonation in this
     * case.
     */
    static final int IMPERSONATION_FAILED = 2;

    /**
     * Sets up the sate of this login module. If the instance throws any
     * <code>Exception</code> during setup it will be ignored for the login
     * processing.
     */
    void init(CallbackHandler callbackHandler, Session session,
            Map<?, ?> options) throws LoginException;

    /**
     * Informs the plugin that the overall login process has succeeded and
     * should now be finalized. This allows the implementation to cleanup any
     * state which has been created during the login process.
     * <p>
     * Regardless of the outcome of this method, the <code>commit</code> method
     * of the <code>DefaultLoginModule</code> is always called. The result of
     * the overall commit process is the worst result of both methods.
     */
    boolean commit() throws LoginException;

    /**
     * Informs the plugin that the overall login process has failed and should
     * not be finalized. This allows the implementation to cleanup any state
     * which has been created during the login process.
     * <p>
     * Regardless of the outcome of this method, the <code>abort</code> method
     * of the <code>DefaultLoginModule</code> is always called. The result of
     * the overall abort process is the worst result of both methods.
     */
    boolean abort() throws LoginException;

    /**
     * Returns the user ID encoded in the given credentials or <code>null</code>
     * if this plugin does not support these Credentials.
     * <p>
     * This method is generally called by the <code>DefaultLoginModule</code> if
     * the {@link #getPrincipal(Credentials)} method returns <code>null</code>.
     * <p>
     * If <code>null</code> is returned the user ID is expected to be provided
     * by the <code>AbstractLoginModule.getUserId(Credentials)</code> method.
     */
    String getUserId(Credentials credentials);

    /**
     * Return a Principal object or <code>null</code>.
     * <p>
     * If <code>null</code> is returned the Principal will be provided by the
     * <code>DefaultLoginModule.getPrincipal</code> method.
     * <p>
     * Generally this method should return <code>null</code> unless the login
     * module has a way of providing a Principal which may be used as the basis
     * for authentication decisions in the repository.
     *
     * @return an instance of the Principal associated with these Credentials or
     *         <code>null</code>
     */
    Principal getPrincipal(Credentials credentials);

    /**
     * Allows for adding additional {@link Principal} objects, such as groups or
     * roles, to the {@link Subject}.
     *
     * @param principals original collection of principals
     */
    void addPrincipals(Set<Principal> principals);

    /**
     * Validate the credentials to identify the given principal. If the
     * credentials identify the principal this method returns <code>true</code>.
     * If the credentials don't identify the principal the method returns
     * <code>false</code> in which case the the <code>authenticate</code> method
     * of the <code>DefaultLoginModule</code> is called.
     *
     * @return <code>true</code> if the credentials identify the principal.
     *         Otherwise <code>false</code> to indicate the plugin cannot
     *         identify the principal from the credentials.
     */
    boolean authenticate(User user, Principal principal, Credentials credentials);

    /**
     * Returns a code indicating either the status of the impersonation attempt,
     * or {@link #IMPERSONATION_DEFAULT} if the impersonation should be handled
     * by the <code>DefaultLoginModule.impersonate</code> method.
     *
     * @return one of {@link #IMPERSONATION_DEFAULT},
     *         {@link #IMPERSONATION_SUCCESS} or {@link #IMPERSONATION_FAILED}
     */
    int impersonate(Principal principal, Credentials credentials)
            throws RepositoryException, FailedLoginException;

}