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