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 }