source: josm/trunk/src/oauth/signpost/OAuthConsumer.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: 7.0 KB
RevLine 
[4231]1/* Copyright (c) 2009 Matthias Kaeppler
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15package oauth.signpost;
16
17import java.io.Serializable;
18
19import oauth.signpost.exception.OAuthCommunicationException;
20import oauth.signpost.exception.OAuthExpectationFailedException;
21import oauth.signpost.exception.OAuthMessageSignerException;
22import oauth.signpost.http.HttpParameters;
23import oauth.signpost.http.HttpRequest;
24import oauth.signpost.signature.AuthorizationHeaderSigningStrategy;
25import oauth.signpost.signature.HmacSha1MessageSigner;
26import oauth.signpost.signature.OAuthMessageSigner;
27import oauth.signpost.signature.QueryStringSigningStrategy;
28import oauth.signpost.signature.SigningStrategy;
29
30/**
31 * <p>
32 * Exposes a simple interface to sign HTTP requests using a given OAuth token
33 * and secret. Refer to {@link OAuthProvider} how to retrieve a valid token and
34 * token secret.
35 * </p>
36 * <p>
37 * HTTP messages are signed as follows:
38 * <p>
[10831]39 *
[4231]40 * <pre>
41 * // exchange the arguments with the actual token/secret pair
42 * OAuthConsumer consumer = new DefaultOAuthConsumer(&quot;1234&quot;, &quot;5678&quot;);
[10831]43 *
[4231]44 * URL url = new URL(&quot;http://example.com/protected.xml&quot;);
45 * HttpURLConnection request = (HttpURLConnection) url.openConnection();
[10831]46 *
[4231]47 * consumer.sign(request);
[10831]48 *
[4231]49 * request.connect();
50 * </pre>
[10831]51 *
[4231]52 * </p>
53 * </p>
[10831]54 *
[4231]55 * @author Matthias Kaeppler
56 */
57public interface OAuthConsumer extends Serializable {
58
59 /**
60 * Sets the message signer that should be used to generate the OAuth
61 * signature.
[10831]62 *
[4231]63 * @param messageSigner
64 * the signer
65 * @see HmacSha1MessageSigner
66 */
67 public void setMessageSigner(OAuthMessageSigner messageSigner);
68
69 /**
70 * Allows you to add parameters (typically OAuth parameters such as
71 * oauth_callback or oauth_verifier) which will go directly into the signer,
72 * i.e. you don't have to put them into the request first. The consumer's
73 * {@link SigningStrategy} will then take care of writing them to the
[6849]74 * correct part of the request before it is sent. This is useful if you want
75 * to pre-set custom OAuth parameters. Note that these parameters are
76 * expected to already be percent encoded -- they will be simply merged
77 * as-is. <b>BE CAREFUL WITH THIS METHOD! Your service provider may decide
78 * to ignore any non-standard OAuth params when computing the signature.</b>
[10831]79 *
[4231]80 * @param additionalParameters
81 * the parameters
82 */
83 public void setAdditionalParameters(HttpParameters additionalParameters);
84
85 /**
86 * Defines which strategy should be used to write a signature to an HTTP
87 * request.
[10831]88 *
[4231]89 * @param signingStrategy
90 * the strategy
91 * @see AuthorizationHeaderSigningStrategy
92 * @see QueryStringSigningStrategy
93 */
94 public void setSigningStrategy(SigningStrategy signingStrategy);
95
96 /**
97 * <p>
98 * Causes the consumer to always include the oauth_token parameter to be
99 * sent, even if blank. If you're seeing 401s during calls to
100 * {@link OAuthProvider#retrieveRequestToken}, try setting this to true.
101 * </p>
[10831]102 *
[4231]103 * @param enable
104 * true or false
105 */
106 public void setSendEmptyTokens(boolean enable);
107
108 /**
109 * Signs the given HTTP request by writing an OAuth signature (and other
110 * required OAuth parameters) to it. Where these parameters are written
111 * depends on the current {@link SigningStrategy}.
[10831]112 *
[4231]113 * @param request
114 * the request to sign
115 * @return the request object passed as an argument
116 * @throws OAuthMessageSignerException
117 * @throws OAuthExpectationFailedException
118 * @throws OAuthCommunicationException
119 */
120 public HttpRequest sign(HttpRequest request) throws OAuthMessageSignerException,
121 OAuthExpectationFailedException, OAuthCommunicationException;
122
123 /**
124 * <p>
125 * Signs the given HTTP request by writing an OAuth signature (and other
126 * required OAuth parameters) to it. Where these parameters are written
127 * depends on the current {@link SigningStrategy}.
128 * </p>
129 * This method accepts HTTP library specific request objects; the consumer
130 * implementation must ensure that only those request types are passed which
131 * it supports.
[10831]132 *
[4231]133 * @param request
134 * the request to sign
135 * @return the request object passed as an argument
136 * @throws OAuthMessageSignerException
137 * @throws OAuthExpectationFailedException
138 * @throws OAuthCommunicationException
139 */
140 public HttpRequest sign(Object request) throws OAuthMessageSignerException,
141 OAuthExpectationFailedException, OAuthCommunicationException;
142
143 /**
144 * <p>
145 * "Signs" the given URL by appending all OAuth parameters to it which are
146 * required for message signing. The assumed HTTP method is GET.
147 * Essentially, this is equivalent to signing an HTTP GET request, but it
148 * can be useful if your application requires clickable links to protected
149 * resources, i.e. when your application does not have access to the actual
150 * request that is being sent.
151 * </p>
[10831]152 *
[4231]153 * @param url
154 * the input URL. May have query parameters.
155 * @return the input URL, with all necessary OAuth parameters attached as a
156 * query string. Existing query parameters are preserved.
157 * @throws OAuthMessageSignerException
158 * @throws OAuthExpectationFailedException
159 * @throws OAuthCommunicationException
160 */
161 public String sign(String url) throws OAuthMessageSignerException,
162 OAuthExpectationFailedException, OAuthCommunicationException;
163
164 /**
165 * Sets the OAuth token and token secret used for message signing.
[10831]166 *
[4231]167 * @param token
168 * the token
169 * @param tokenSecret
170 * the token secret
171 */
172 public void setTokenWithSecret(String token, String tokenSecret);
173
174 public String getToken();
175
176 public String getTokenSecret();
177
178 public String getConsumerKey();
179
180 public String getConsumerSecret();
181
182 /**
183 * Returns all parameters collected from the HTTP request during message
184 * signing (this means the return value may be NULL before a call to
185 * {@link #sign}), plus all required OAuth parameters that were added
186 * because the request didn't contain them beforehand. In other words, this
187 * is the exact set of parameters that were used for creating the message
188 * signature.
[10831]189 *
[4231]190 * @return the request parameters used for message signing
191 */
192 public HttpParameters getRequestParameters();
193}
Note: See TracBrowser for help on using the repository browser.