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 * 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 * @return Panel 079 */ 080 Component getPreferencesDecorationPanel(); 081}