001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.gui.oauth;
003
004import java.util.Objects;
005
006import org.openstreetmap.josm.data.oauth.OAuthParameters;
007import org.openstreetmap.josm.data.oauth.OAuthToken;
008import org.openstreetmap.josm.gui.widgets.VerticallyScrollablePanel;
009import org.openstreetmap.josm.tools.CheckParameterUtil;
010
011/**
012 * This is the abstract base class for the three authorisation UIs.
013 *
014 * @since 2746
015 */
016public abstract class AbstractAuthorizationUI extends VerticallyScrollablePanel {
017    /**
018     * The property name for the Access Token property
019     */
020    public static final String ACCESS_TOKEN_PROP = AbstractAuthorizationUI.class.getName() + ".accessToken";
021
022    private String apiUrl;
023    private final AdvancedOAuthPropertiesPanel pnlAdvancedProperties = new AdvancedOAuthPropertiesPanel();
024    private transient OAuthToken accessToken;
025
026    /**
027     * Constructs a new {@code AbstractAuthorizationUI} without API URL.
028     * @since 10189
029     */
030    protected AbstractAuthorizationUI() {
031    }
032
033    /**
034     * Constructs a new {@code AbstractAuthorizationUI} for the given API URL.
035     * @param apiUrl The OSM API URL
036     * @since 5422
037     */
038    protected AbstractAuthorizationUI(String apiUrl) {
039        setApiUrl(apiUrl);
040    }
041
042    protected void fireAccessTokenChanged(OAuthToken oldValue, OAuthToken newValue) {
043        firePropertyChange(ACCESS_TOKEN_PROP, oldValue, newValue);
044    }
045
046    /**
047     * Replies the URL of the OSM API for which this UI is currently trying to retrieve an OAuth
048     * Access Token
049     *
050     * @return the API URL
051     */
052    public String getApiUrl() {
053        return apiUrl;
054    }
055
056    /**
057     * Sets the URL of the OSM API for which this UI is currently trying to retrieve an OAuth
058     * Access Token
059     *
060     * @param apiUrl the api URL
061     */
062    public void setApiUrl(String apiUrl) {
063        this.apiUrl = apiUrl;
064        this.pnlAdvancedProperties.setApiUrl(apiUrl);
065    }
066
067    /**
068     * Replies the panel for entering advanced OAuth parameters (see {@link OAuthParameters})
069     *
070     * @return the panel for entering advanced OAuth parameters
071     * @see #getOAuthParameters()
072     */
073    protected AdvancedOAuthPropertiesPanel getAdvancedPropertiesPanel() {
074        return pnlAdvancedProperties;
075    }
076
077    /**
078     * Replies the current set of advanced OAuth parameters in this UI
079     *
080     * @return the current set of advanced OAuth parameters in this UI
081     */
082    public OAuthParameters getOAuthParameters() {
083        return pnlAdvancedProperties.getAdvancedParameters();
084    }
085
086    /**
087     * Replies the retrieved Access Token. null, if no Access Token was retrieved.
088     *
089     * @return the retrieved Access Token
090     */
091    public OAuthToken getAccessToken() {
092        return accessToken;
093    }
094
095    /**
096     * Sets the current Access Token. This will fire a property change event for {@link #ACCESS_TOKEN_PROP}
097     * if the access token has changed
098     *
099     * @param accessToken the new access token. null, to clear the current access token
100     */
101    protected void setAccessToken(OAuthToken accessToken) {
102        OAuthToken oldValue = this.accessToken;
103        this.accessToken = accessToken;
104        if (oldValue == null ^ this.accessToken == null) {
105            fireAccessTokenChanged(oldValue, this.accessToken);
106        } else if (oldValue == null && this.accessToken == null) {
107            // no change - don't fire an event
108        } else if (!Objects.equals(oldValue, this.accessToken)) {
109            fireAccessTokenChanged(oldValue, this.accessToken);
110        }
111    }
112
113    /**
114     * Replies true if this UI currently has an Access Token
115     *
116     * @return true if this UI currently has an Access Token
117     */
118    public boolean hasAccessToken() {
119        return accessToken != null;
120    }
121
122    /**
123     * Replies whether the user has chosen to save the Access Token in the JOSM
124     * preferences or not.
125     *
126     * @return true if the user has chosen to save the Access Token
127     */
128    public abstract boolean isSaveAccessTokenToPreferences();
129
130    /**
131     * Initializes the authorisation UI.
132     *
133     * @param paramApiUrl the API URL. Must not be null.
134     * @throws IllegalArgumentException if paramApiUrl is null
135     */
136    public void initialize(String paramApiUrl) {
137        CheckParameterUtil.ensureParameterNotNull(paramApiUrl, "paramApiUrl");
138        pnlAdvancedProperties.initialize(paramApiUrl);
139    }
140}