source: josm/trunk/src/oauth/signpost/OAuthProvider.java@ 16334

Last change on this file since 16334 was 10831, checked in by Don-vip, 8 years ago

see #13232 - cleanup OAuth signpost code:

  • remove classes unused by JOSM
  • add missing @Override annotations
File size: 10.3 KB
RevLine 
[4231]1/*
2 * Copyright (c) 2009 Matthias Kaeppler Licensed under the Apache License,
3 * Version 2.0 (the "License"); you may not use this file except in compliance
4 * with the License. You may obtain a copy of the License at
5 * http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law
6 * or agreed to in writing, software distributed under the License is
7 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
8 * KIND, either express or implied. See the License for the specific language
9 * governing permissions and limitations under the License.
10 */
11package oauth.signpost;
12
13import java.io.Serializable;
14import java.util.Map;
15
16import oauth.signpost.exception.OAuthCommunicationException;
17import oauth.signpost.exception.OAuthExpectationFailedException;
18import oauth.signpost.exception.OAuthMessageSignerException;
19import oauth.signpost.exception.OAuthNotAuthorizedException;
20import oauth.signpost.http.HttpParameters;
21
22/**
23 * <p>
24 * Supplies an interface that can be used to retrieve request and access tokens
25 * from an OAuth 1.0(a) service provider. A provider object requires an
26 * {@link OAuthConsumer} to sign the token request message; after a token has
27 * been retrieved, the consumer is automatically updated with the token and the
28 * corresponding secret.
29 * </p>
30 * <p>
31 * To initiate the token exchange, create a new provider instance and configure
32 * it with the URLs the service provider exposes for requesting tokens and
33 * resource authorization, e.g.:
34 * </p>
[10831]35 *
[4231]36 * <pre>
37 * OAuthProvider provider = new DefaultOAuthProvider(&quot;http://twitter.com/oauth/request_token&quot;,
38 * &quot;http://twitter.com/oauth/access_token&quot;, &quot;http://twitter.com/oauth/authorize&quot;);
39 * </pre>
40 * <p>
41 * Depending on the HTTP library you use, you may need a different provider
42 * type, refer to the website documentation for how to do that.
43 * </p>
44 * <p>
45 * To receive a request token which the user must authorize, you invoke it using
46 * a consumer instance and a callback URL:
47 * </p>
48 * <p>
[10831]49 *
[4231]50 * <pre>
51 * String url = provider.retrieveRequestToken(consumer, &quot;http://www.example.com/callback&quot;);
52 * </pre>
[10831]53 *
[4231]54 * </p>
55 * <p>
56 * That url must be opened in a Web browser, where the user can grant access to
57 * the resources in question. If that succeeds, the service provider will
58 * redirect to the callback URL and append the blessed request token.
59 * </p>
60 * <p>
61 * That token must now be exchanged for an access token, as such:
62 * </p>
63 * <p>
[10831]64 *
[4231]65 * <pre>
66 * provider.retrieveAccessToken(consumer, nullOrVerifierCode);
67 * </pre>
[10831]68 *
[4231]69 * </p>
70 * <p>
71 * where nullOrVerifierCode is either null if your provided a callback URL in
72 * the previous step, or the pin code issued by the service provider to the user
73 * if the request was out-of-band (cf. {@link OAuth#OUT_OF_BAND}.
74 * </p>
75 * <p>
76 * The consumer used during token handshakes is now ready for signing.
77 * </p>
[10831]78 *
[4231]79 * @see OAuthProviderListener
80 */
81public interface OAuthProvider extends Serializable {
82
83 /**
84 * Queries the service provider for a request token.
85 * <p>
86 * <b>Pre-conditions:</b> the given {@link OAuthConsumer} must have a valid
87 * consumer key and consumer secret already set.
88 * </p>
89 * <p>
90 * <b>Post-conditions:</b> the given {@link OAuthConsumer} will have an
91 * unauthorized request token and token secret set.
92 * </p>
[10831]93 *
[4231]94 * @param consumer
95 * the {@link OAuthConsumer} that should be used to sign the request
96 * @param callbackUrl
97 * Pass an actual URL if your app can receive callbacks and you want
98 * to get informed about the result of the authorization process.
99 * Pass {@link OAuth.OUT_OF_BAND} if the service provider implements
100 * OAuth 1.0a and your app cannot receive callbacks. Pass null if the
101 * service provider implements OAuth 1.0 and your app cannot receive
102 * callbacks. Please note that some services (among them Twitter)
103 * will fail authorization if you pass a callback URL but register
104 * your application as a desktop app (which would only be able to
105 * handle OOB requests).
[6849]106 * @param customOAuthParams
107 * you can pass custom OAuth parameters here which will go directly
108 * into the signer, i.e. you don't have to put them into the request
109 * first. This is useful for pre-setting OAuth params for signing.
110 * Pass them sequentially in key/value order.
[4231]111 * @return The URL to which the user must be sent in order to authorize the
112 * consumer. It includes the unauthorized request token (and in the
113 * case of OAuth 1.0, the callback URL -- 1.0a clients send along
114 * with the token request).
115 * @throws OAuthMessageSignerException
116 * if signing the request failed
117 * @throws OAuthNotAuthorizedException
118 * if the service provider rejected the consumer
119 * @throws OAuthExpectationFailedException
120 * if required parameters were not correctly set by the consumer or
121 * service provider
122 * @throws OAuthCommunicationException
123 * if server communication failed
124 */
[6849]125 public String retrieveRequestToken(OAuthConsumer consumer, String callbackUrl,
126 String... customOAuthParams) throws OAuthMessageSignerException,
127 OAuthNotAuthorizedException, OAuthExpectationFailedException,
128 OAuthCommunicationException;
[4231]129
130 /**
131 * Queries the service provider for an access token.
132 * <p>
133 * <b>Pre-conditions:</b> the given {@link OAuthConsumer} must have a valid
134 * consumer key, consumer secret, authorized request token and token secret
135 * already set.
136 * </p>
137 * <p>
138 * <b>Post-conditions:</b> the given {@link OAuthConsumer} will have an
139 * access token and token secret set.
140 * </p>
[10831]141 *
[4231]142 * @param consumer
143 * the {@link OAuthConsumer} that should be used to sign the request
144 * @param oauthVerifier
145 * <b>NOTE: Only applies to service providers implementing OAuth
146 * 1.0a. Set to null if the service provider is still using OAuth
147 * 1.0.</b> The verification code issued by the service provider
148 * after the the user has granted the consumer authorization. If the
149 * callback method provided in the previous step was
150 * {@link OAuth.OUT_OF_BAND}, then you must ask the user for this
151 * value. If your app has received a callback, the verfication code
152 * was passed as part of that request instead.
[6849]153 * @param customOAuthParams
154 * you can pass custom OAuth parameters here which will go directly
155 * into the signer, i.e. you don't have to put them into the request
156 * first. This is useful for pre-setting OAuth params for signing.
157 * Pass them sequentially in key/value order.
[4231]158 * @throws OAuthMessageSignerException
159 * if signing the request failed
160 * @throws OAuthNotAuthorizedException
161 * if the service provider rejected the consumer
162 * @throws OAuthExpectationFailedException
163 * if required parameters were not correctly set by the consumer or
164 * service provider
165 * @throws OAuthCommunicationException
166 * if server communication failed
167 */
[6849]168 public void retrieveAccessToken(OAuthConsumer consumer, String oauthVerifier,
169 String... customOAuthParams) throws OAuthMessageSignerException,
170 OAuthNotAuthorizedException, OAuthExpectationFailedException,
171 OAuthCommunicationException;
[4231]172
173 /**
174 * Any additional non-OAuth parameters returned in the response body of a
175 * token request can be obtained through this method. These parameters will
176 * be preserved until the next token request is issued. The return value is
177 * never null.
178 */
179 public HttpParameters getResponseParameters();
180
181 /**
182 * Subclasses must use this setter to preserve any non-OAuth query
183 * parameters contained in the server response. It's the caller's
184 * responsibility that any OAuth parameters be removed beforehand.
[10831]185 *
[4231]186 * @param parameters
187 * the map of query parameters served by the service provider in the
188 * token response
189 */
190 public void setResponseParameters(HttpParameters parameters);
191
192 /**
193 * Use this method to set custom HTTP headers to be used for the requests
194 * which are sent to retrieve tokens. @deprecated THIS METHOD HAS BEEN
195 * DEPRECATED. Use {@link OAuthProviderListener} to customize requests.
[10831]196 *
[4231]197 * @param header
198 * The header name (e.g. 'WWW-Authenticate')
199 * @param value
200 * The header value (e.g. 'realm=www.example.com')
201 */
202 @Deprecated
203 public void setRequestHeader(String header, String value);
204
205 /**
206 * @deprecated THIS METHOD HAS BEEN DEPRECATED. Use
207 * {@link OAuthProviderListener} to customize requests.
208 * @return all request headers set via {@link #setRequestHeader}
209 */
210 @Deprecated
211 public Map<String, String> getRequestHeaders();
212
213 /**
214 * @param isOAuth10aProvider
215 * set to true if the service provider supports OAuth 1.0a. Note that
216 * you need only call this method if you reconstruct a provider
217 * object in between calls to retrieveRequestToken() and
218 * retrieveAccessToken() (i.e. if the object state isn't preserved).
219 * If instead those two methods are called on the same provider
220 * instance, this flag will be deducted automatically based on the
221 * server response during retrieveRequestToken(), so you can simply
222 * ignore this method.
223 */
224 public void setOAuth10a(boolean isOAuth10aProvider);
225
226 /**
227 * @return true if the service provider supports OAuth 1.0a. Note that the
228 * value returned here is only meaningful after you have already
229 * performed the token handshake, otherwise there is no way to
230 * determine what version of the OAuth protocol the service provider
231 * implements.
232 */
233 public boolean isOAuth10a();
234
235 public String getRequestTokenEndpointUrl();
236
237 public String getAccessTokenEndpointUrl();
238
239 public String getAuthorizationWebsiteUrl();
240
241 public void setListener(OAuthProviderListener listener);
242
243 public void removeListener(OAuthProviderListener listener);
244}
Note: See TracBrowser for help on using the repository browser.