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 thrown 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 thrown 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     *
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     * @throws CredentialsAgentException thrown if a problem occurs in a implementation of this interface
053
054     */
055    CredentialsAgentResponse getCredentials(RequestorType requestorType, String host, boolean noSuccessWithLastResponse) throws CredentialsAgentException;
056
057    /**
058     * Lookup the current OAuth Access Token to access the OSM server. Replies null, if no
059     * Access Token is currently managed by this CredentialAgent.
060     *
061     * @return the current OAuth Access Token to access the OSM server.
062     * @throws CredentialsAgentException thrown if something goes wrong
063     */
064    OAuthToken lookupOAuthAccessToken() throws CredentialsAgentException;
065
066    /**
067     * Stores the OAuth Access Token <code>accessToken</code>.
068     *
069     * @param accessToken the access Token. null, to remove the Access Token.
070     * @throws CredentialsAgentException thrown if something goes wrong
071     */
072    void storeOAuthAccessToken(OAuthToken accessToken) throws CredentialsAgentException;
073
074
075    /**
076     * Provide a Panel that is shown below the API password / username fields
077     * in the JOSM Preferences. (E.g. a warning that password is saved unencrypted.)
078     */
079    Component getPreferencesDecorationPanel();
080
081}