/*
 * Copyright (C) 2010, Christian Halstrick <christian.halstrick@sap.com>,
 * Copyright (C) 2010, Stefan Lay <stefan.lay@sap.com> and others
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Distribution License v. 1.0 which is available at
 * https://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

package org.eclipse.jgit.transport;

import java.util.List;

import org.eclipse.jgit.errors.UnsupportedCredentialItem;

Provide credentials for use in connecting to Git repositories. Implementors are strongly encouraged to support at least the minimal Username and Password items. More sophisticated implementors may implement additional types, such as StringType. CredentialItems are usually presented in bulk, allowing implementors to combine them into a single UI widget and streamline the authentication process for an end-user. 
See Also:
UsernamePasswordCredentialsProvider/**
 * Provide credentials for use in connecting to Git repositories.
 *
 * Implementors are strongly encouraged to support at least the minimal
 * {@link org.eclipse.jgit.transport.CredentialItem.Username} and
 * {@link org.eclipse.jgit.transport.CredentialItem.Password} items. More
 * sophisticated implementors may implement additional types, such as
 * {@link org.eclipse.jgit.transport.CredentialItem.StringType}.
 *
 * CredentialItems are usually presented in bulk, allowing implementors to
 * combine them into a single UI widget and streamline the authentication
 * process for an end-user.
 *
 * @see UsernamePasswordCredentialsProvider
 */
public abstract class CredentialsProvider {
	private static volatile CredentialsProvider defaultProvider;

	
Get the default credentials provider, or null.
Returns:
the default credentials provider, or null./**
	 * Get the default credentials provider, or null.
	 *
	 * @return the default credentials provider, or null.
	 */
	public static CredentialsProvider getDefault() {
		return defaultProvider;
	}

	
Set the default credentials provider.
Params:
p – 
           the new default provider, may be null to select no default./**
	 * Set the default credentials provider.
	 *
	 * @param p
	 *            the new default provider, may be null to select no default.
	 */
	public static void setDefault(CredentialsProvider p) {
		defaultProvider = p;
	}

	
Whether any of the passed items is null
Params:
items – 
           credential items to check
Returns:
true if any of the passed items is null, false otherwise
Since:
4.2/**
	 * Whether any of the passed items is null
	 *
	 * @param items
	 *            credential items to check
	 * @return {@code true} if any of the passed items is null, {@code false}
	 *         otherwise
	 * @since 4.2
	 */
	protected static boolean isAnyNull(CredentialItem... items) {
		for (CredentialItem i : items)
			if (i == null)
				return true;
		return false;
	}

	
Check if the provider is interactive with the end-user.
An interactive provider may try to open a dialog box, or prompt for input
on the terminal, and will wait for a user response. A non-interactive
provider will either populate CredentialItems, or fail.
Returns:
true if the provider is interactive with the end-user./**
	 * Check if the provider is interactive with the end-user.
	 *
	 * An interactive provider may try to open a dialog box, or prompt for input
	 * on the terminal, and will wait for a user response. A non-interactive
	 * provider will either populate CredentialItems, or fail.
	 *
	 * @return {@code true} if the provider is interactive with the end-user.
	 */
	public abstract boolean isInteractive();

	
Check if the provider can supply the necessary CredentialItems. 
Params:
items – 
           the items the application requires to complete authentication.
Returns:
true if this CredentialsProvider supports all of the items supplied./**
	 * Check if the provider can supply the necessary
	 * {@link org.eclipse.jgit.transport.CredentialItem}s.
	 *
	 * @param items
	 *            the items the application requires to complete authentication.
	 * @return {@code true} if this
	 *         {@link org.eclipse.jgit.transport.CredentialsProvider} supports
	 *         all of the items supplied.
	 */
	public abstract boolean supports(CredentialItem... items);

	
Ask for the credential items to be populated.
Params:
uri – 
           the URI of the remote resource that needs authentication.
items – 
           the items the application requires to complete authentication.
Throws:
UnsupportedCredentialItem – 
            if one of the items supplied is not supported.
Returns:
true if the request was successful and values were supplied; false if the user canceled the request and did not supply all requested values./**
	 * Ask for the credential items to be populated.
	 *
	 * @param uri
	 *            the URI of the remote resource that needs authentication.
	 * @param items
	 *            the items the application requires to complete authentication.
	 * @return {@code true} if the request was successful and values were
	 *         supplied; {@code false} if the user canceled the request and did
	 *         not supply all requested values.
	 * @throws org.eclipse.jgit.errors.UnsupportedCredentialItem
	 *             if one of the items supplied is not supported.
	 */
	public abstract boolean get(URIish uri, CredentialItem... items)
			throws UnsupportedCredentialItem;

	
Ask for the credential items to be populated.
Params:
uri – 
           the URI of the remote resource that needs authentication.
items – 
           the items the application requires to complete authentication.
Throws:
UnsupportedCredentialItem – 
            if one of the items supplied is not supported.
Returns:
true if the request was successful and values were supplied; false if the user canceled the request and did not supply all requested values./**
	 * Ask for the credential items to be populated.
	 *
	 * @param uri
	 *            the URI of the remote resource that needs authentication.
	 * @param items
	 *            the items the application requires to complete authentication.
	 * @return {@code true} if the request was successful and values were
	 *         supplied; {@code false} if the user canceled the request and did
	 *         not supply all requested values.
	 * @throws org.eclipse.jgit.errors.UnsupportedCredentialItem
	 *             if one of the items supplied is not supported.
	 */
	public boolean get(URIish uri, List<CredentialItem> items)
			throws UnsupportedCredentialItem {
		return get(uri, items.toArray(new CredentialItem[0]));
	}

	
Reset the credentials provider for the given URI
Params:
uri –  a URIish object./**
	 * Reset the credentials provider for the given URI
	 *
	 * @param uri
	 *            a {@link org.eclipse.jgit.transport.URIish} object.
	 */
	public void reset(URIish uri) {
		// default does nothing
	}
}