1 | // License: GPL. For details, see LICENSE file.
|
---|
2 | package org.openstreetmap.josm.io.auth;
|
---|
3 |
|
---|
4 | import java.awt.Component;
|
---|
5 | import java.net.Authenticator.RequestorType;
|
---|
6 | import java.net.PasswordAuthentication;
|
---|
7 |
|
---|
8 | import org.openstreetmap.josm.data.oauth.OAuthToken;
|
---|
9 |
|
---|
10 | /**
|
---|
11 | * A CredentialsAgent manages two credentials:
|
---|
12 | * <ul>
|
---|
13 | * <li>the credential for {@link RequestorType#SERVER} which is equal to the OSM API credentials
|
---|
14 | * in JOSM</li>
|
---|
15 | * <li>the credential for {@link RequestorType#PROXY} which is equal to the credentials for an
|
---|
16 | * optional HTTP proxy server a user may use</li>
|
---|
17 | * </ul>
|
---|
18 | *
|
---|
19 | * In addition, it manages an OAuth Access Token for accessing the OSM server.
|
---|
20 | */
|
---|
21 | public interface CredentialsAgent {
|
---|
22 |
|
---|
23 | /**
|
---|
24 | * Looks up the credentials for a given type.
|
---|
25 | *
|
---|
26 | * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
|
---|
27 | * for a proxy server
|
---|
28 | * @param host the hostname for these credentials
|
---|
29 | * @return the credentials
|
---|
30 | * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
|
---|
31 | */
|
---|
32 | PasswordAuthentication lookup(RequestorType requestorType, String host) throws CredentialsAgentException;
|
---|
33 |
|
---|
34 | /**
|
---|
35 | * Saves the credentials in <code>credentials</code> for the given service type.
|
---|
36 | *
|
---|
37 | * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
|
---|
38 | * for a proxy server
|
---|
39 | * @param host the hostname for these credentials
|
---|
40 | * @param credentials the credentials
|
---|
41 | * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
|
---|
42 | */
|
---|
43 | void store(RequestorType requestorType, String host, PasswordAuthentication credentials) throws CredentialsAgentException;
|
---|
44 |
|
---|
45 | /**
|
---|
46 | * Returns the credentials needed to to access host.
|
---|
47 | * @param requestorType the type of service. {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY}
|
---|
48 | * for a proxy server
|
---|
49 | * @param host the hostname for these credentials
|
---|
50 | * @param noSuccessWithLastResponse true, if the last request with the supplied credentials failed; false otherwise.
|
---|
51 | * If true, implementations of this interface are advised to prompt the user for new credentials.
|
---|
52 | * @return the credentials
|
---|
53 | * @throws CredentialsAgentException if a problem occurs in a implementation of this interface
|
---|
54 | */
|
---|
55 | CredentialsAgentResponse getCredentials(RequestorType requestorType, String host, boolean noSuccessWithLastResponse)
|
---|
56 | throws CredentialsAgentException;
|
---|
57 |
|
---|
58 | /**
|
---|
59 | * Lookup the current OAuth Access Token to access the OSM server. Replies null, if no
|
---|
60 | * Access Token is currently managed by this CredentialAgent.
|
---|
61 | *
|
---|
62 | * @return the current OAuth Access Token to access the OSM server.
|
---|
63 | * @throws CredentialsAgentException if something goes wrong
|
---|
64 | */
|
---|
65 | OAuthToken lookupOAuthAccessToken() throws CredentialsAgentException;
|
---|
66 |
|
---|
67 | /**
|
---|
68 | * Stores the OAuth Access Token <code>accessToken</code>.
|
---|
69 | *
|
---|
70 | * @param accessToken the access Token. null, to remove the Access Token.
|
---|
71 | * @throws CredentialsAgentException if something goes wrong
|
---|
72 | */
|
---|
73 | void storeOAuthAccessToken(OAuthToken accessToken) throws CredentialsAgentException;
|
---|
74 |
|
---|
75 | /**
|
---|
76 | * Purges the internal credentials cache for the given requestor type.
|
---|
77 | * @param requestorType the type of service.
|
---|
78 | * {@link RequestorType#SERVER} for the OSM API server, {@link RequestorType#PROXY} for a proxy server
|
---|
79 | * @since 12992
|
---|
80 | */
|
---|
81 | void purgeCredentialsCache(RequestorType requestorType);
|
---|
82 |
|
---|
83 | /**
|
---|
84 | * Provide a Panel that is shown below the API password / username fields
|
---|
85 | * in the JOSM Preferences. (E.g. a warning that password is saved unencrypted.)
|
---|
86 | * @return Panel
|
---|
87 | */
|
---|
88 | Component getPreferencesDecorationPanel();
|
---|
89 | }
|
---|