/**
 * Copyright 2010 JBoss Inc
 *
 * Licensed 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.eclipse.webdav.http.client;

import java.net.URL;
import java.util.Map;

/**
 * Implementations of this interface are used by clients to store and
 * retrieve information for authentication purposes.
 * <p>
 * <b>Note:</b> This class/interface is part of an interim API that is still under 
 * development and expected to change significantly before reaching stability. 
 * It is being made available at this early stage to solicit feedback from pioneering 
 * adopters on the understanding that any code that uses this API will almost 
 * certainly be broken (repeatedly) as the API evolves.
 * </p>
 */
public interface IAuthenticator {

	/**
	 * Adds the given authentication information to the store. The
	 * information is relevant for the specified protection space and the
	 * given authentication scheme. The protection space is defined by the
	 * combination of the given server URL and realm. The authentication 
	 * scheme determines what the authentication information contains and how 
	 * it should be used. The authentication information is a <code>Map</code> 
	 * of <code>String</code> to <code>String</code> and typically
	 * contain information such as usernames and passwords.
	 *
	 * @param serverUrl the URL identifying the server for this authentication
	 *		information. For example, "http://www.hostname.com/".
	 * @param realm the subsection of the given server to which this
	 *		authentication information applies.  For example,
	 *		"realm1@hostname.com" or "" for no realm.
	 * @param scheme the scheme for which this authentication information
	 *		applies. For example, "Basic" or "" for no authentication scheme
	 * @param info a <code>Map</code> containing authentication information 
	 *		such as usernames and passwords
	 */
	public void addAuthenticationInfo(URL serverUrl, String realm, String scheme, Map info);

	/**
	 * Adds the specified resource to the protection space specified by the
	 * given realm. All resources at or deeper than the depth of the last
	 * symbolic element in the path of the given resource URL are assumed to
	 * be in the same protection space.
	 *
	 * @param resourceUrl the URL identifying the resources to be added to
	 *		the specified protection space. For example,
	 *		"http://www.hostname.com/folder/".
	 * @param realm the name of the protection space. For example,
	 *		"realm1@hostname.com"
	 */
	public void addProtectionSpace(URL resourceUrl, String realm);

	/**
	 * Returns the authentication information for the specified protection
	 * space and given authentication scheme. The protection space is defined
	 * by the given server URL and realm. Returns <code>null</code> if no
	 * such information exists.
	 * <p>This method is similar to <code>requestAuthenticationInfo</code>
	 * except the user is not prompted for the result. Instead, the store is
	 * queried for the information (such as username and password).
	 *
	 * @param serverUrl the URL identifying the server for the authentication
	 *		information. For example, "http://www.hostname.com/".
	 * @param realm the subsection of the given server to which the
	 *		authentication information applies.  For example,
	 *		"realm1@hostname.com" or "" for no realm.
	 * @param scheme the scheme for which the authentication information
	 *		applies. For example, "Basic" or "" for no authentication scheme
	 * @return the authentication information for the specified protection
	 *		space and given authentication scheme, or <code>null</code> if no
	 *		such information exists
	 * @see #requestAuthenticationInfo(URL, String, String)
	 */
	public Map getAuthenticationInfo(URL serverUrl, String realm, String scheme);

	/**
	 * Returns the protection space (realm) for the specified resource, or
	 * <code>null</code> if the realm is unknown.
	 *
	 * @param resourceUrl the URL of the resource whose protection space is
	 *		returned. For example, "http://www.hostname.com/folder/".
	 * @return the protection space (realm) for the specified resource, or
	 *		<code>null</code> if the realm is unknown
	 */
	public String getProtectionSpace(URL resourceUrl);

	/**
	 * Returns the authentication information for the specified protection
	 * space and given authentication scheme. The protection space is defined
	 * by the given server URL and realm. Returns <code>null</code> if no
	 * such information exists.
	 * <p>This method is similar to <code>getAuthenticationInfo</code> except
	 * the store is usually not queried for the result. Instead, the user is
	 * prompted for the information (such as username and password).
	 *
	 * @param resourceUrl the URL identifying the server for the authentication
	 *		information. For example, "http://www.hostname.com/".
	 * @param realm the subsection of the given server to which the
	 *		authentication information applies.  For example,
	 *		"realm1@hostname.com" or "" for no realm.
	 * @param scheme the scheme for which the authentication information
	 *		applies. For example, "Basic" or "" for no authentication scheme
	 * @return the authentication information for the specified protection
	 *		space and given authentication scheme, or <code>null</code> if no
	 *		such information exists
	 * @see #getAuthenticationInfo(URL, String, String)
	 */
	public Map requestAuthenticationInfo(URL resourceUrl, String realm, String scheme);
}
