001    // License: GPL. For details, see LICENSE file.
002    package org.openstreetmap.josm.io.auth;
003    
004    import java.awt.Component;
005    import java.net.PasswordAuthentication;
006    import java.net.Authenticator.RequestorType;
007    
008    import 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     */
021    public interface CredentialsAgent {
022    
023        /**
024         * Looks up the credentials for a given type.
025         *
026         * @param the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
027         * for a proxy server
028         * @return the credentials
029         * @throws CredentialsAgentException thrown if a problem occurs in a implementation of this interface
030         */
031        PasswordAuthentication lookup(RequestorType requestorType, String host) throws CredentialsAgentException;
032    
033        /**
034         * Saves the credentials in <code>credentials</code> for the given service type.
035         *
036         * @param the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
037         * for a proxy server
038         * @param credentials the credentials
039         * @throws CredentialsManagerException thrown if a problem occurs in a implementation of this interface
040         */
041        void store(RequestorType requestorType, String host, PasswordAuthentication credentials) throws CredentialsAgentException;
042    
043        /**
044         *
045         * @param requestorType  the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
046         * for a proxy server
047         * @param noSuccessWithLastResponse true, if the last request with the supplied credentials failed; false otherwise.
048         * If true, implementations of this interface are advised to prompt the user for new credentials.
049         * @throws CredentialsAgentException thrown if a problem occurs in a implementation of this interface
050    
051         */
052        CredentialsAgentResponse getCredentials(RequestorType requestorType, String host, boolean noSuccessWithLastResponse) throws CredentialsAgentException;
053    
054        /**
055         * Lookup the current OAuth Access Token to access the OSM server. Replies null, if no
056         * Access Token is currently managed by this CredentialAgent.
057         *
058         * @return the current OAuth Access Token to access the OSM server.
059         * @throws CredentialsAgentException thrown if something goes wrong
060         */
061        OAuthToken lookupOAuthAccessToken() throws CredentialsAgentException;
062    
063        /**
064         * Stores the OAuth Access Token <code>accessToken</code>.
065         *
066         * @param accessToken the access Token. null, to remove the Access Token.
067         * @throws CredentialsAgentException thrown if something goes wrong
068         */
069        void storeOAuthAccessToken(OAuthToken accessToken) throws CredentialsAgentException;
070    
071    
072        /**
073         * Provide a Panel that is shown below the API password / username fields
074         * in the JOSM Preferences. (E.g. a warning that password is saved unencrypted.)
075         */
076        Component getPreferencesDecorationPanel();
077    
078    }