001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.io.auth;
003
004import java.awt.Component;
005import java.net.Authenticator.RequestorType;
006import java.net.PasswordAuthentication;
007
008import org.openstreetmap.josm.data.oauth.OAuthToken;
009
010/**
011 * A CredentialsAgent manages two credentials:
012 * <ul>
013 *   <li>the credential for {@link RequestorType#SERVER} which is equal to the OSM API credentials
014 *   in JOSM</li>
015 *   <li>the credential for {@link RequestorType#PROXY} which is equal to the credentials for an
016 *   optional HTTP proxy server a user may use</li>
017 *  </ul>
018 *
019 *  In addition, it manages an OAuth Access Token for accessing the OSM server.
020 */
021public interface CredentialsAgent {
022
023    /**
024     * Looks up the credentials for a given type.
025     *
026     * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
027     * for a proxy server
028     * @param host the hostname for these credentials
029     * @return the credentials
030     * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
031     */
032    PasswordAuthentication lookup(RequestorType requestorType, String host) throws CredentialsAgentException;
033
034    /**
035     * Saves the credentials in <code>credentials</code> for the given service type.
036     *
037     * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
038     * for a proxy server
039     * @param host the hostname for these credentials
040     * @param credentials the credentials
041     * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
042     */
043    void store(RequestorType requestorType, String host, PasswordAuthentication credentials) throws CredentialsAgentException;
044
045    /**
046     * Returns the credentials needed to to access host.
047     * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
048     * for a proxy server
049     * @param host the hostname for these credentials
050     * @param noSuccessWithLastResponse true, if the last request with the supplied credentials failed; false otherwise.
051     * If true, implementations of this interface are advised to prompt the user for new credentials.
052     * @return the credentials
053     * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
054     */
055    CredentialsAgentResponse getCredentials(RequestorType requestorType, String host, boolean noSuccessWithLastResponse)
056            throws CredentialsAgentException;
057
058    /**
059     * Lookup the current OAuth Access Token to access the OSM server. Replies null, if no
060     * Access Token is currently managed by this CredentialAgent.
061     *
062     * @return the current OAuth Access Token to access the OSM server.
063     * @throws CredentialsAgentException if something goes wrong
064     */
065    OAuthToken lookupOAuthAccessToken() throws CredentialsAgentException;
066
067    /**
068     * Stores the OAuth Access Token <code>accessToken</code>.
069     *
070     * @param accessToken the access Token. null, to remove the Access Token.
071     * @throws CredentialsAgentException if something goes wrong
072     */
073    void storeOAuthAccessToken(OAuthToken accessToken) throws CredentialsAgentException;
074
075    /**
076     * Purges the internal credentials cache for the given requestor type.
077     * @param requestorType the type of service.
078     * {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY} for a proxy server
079     * @since 12992
080     */
081    void purgeCredentialsCache(RequestorType requestorType);
082
083    /**
084     * Provide a Panel that is shown below the API password / username fields
085     * in the JOSM Preferences. (E.g. a warning that password is saved unencrypted.)
086     * @return Panel
087     */
088    Component getPreferencesDecorationPanel();
089}