001/*
002 * Copyright (c) 2010-2024 Mark Allen, Norbert Bartels.
003 *
004 * Permission is hereby granted, free of charge, to any person obtaining a copy
005 * of this software and associated documentation files (the "Software"), to deal
006 * in the Software without restriction, including without limitation the rights
007 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
008 * copies of the Software, and to permit persons to whom the Software is
009 * furnished to do so, subject to the following conditions:
010 *
011 * The above copyright notice and this permission notice shall be included in
012 * all copies or substantial portions of the Software.
013 *
014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
015 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
016 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
017 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
018 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
019 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
020 * THE SOFTWARE.
021 */
022package com.restfb;
023
024import java.util.List;
025
026import com.restfb.batch.BatchRequest;
027import com.restfb.batch.BatchResponse;
028import com.restfb.exception.*;
029import com.restfb.exception.devicetoken.FacebookDeviceTokenCodeExpiredException;
030import com.restfb.exception.devicetoken.FacebookDeviceTokenDeclinedException;
031import com.restfb.exception.devicetoken.FacebookDeviceTokenPendingException;
032import com.restfb.exception.devicetoken.FacebookDeviceTokenSlowdownException;
033import com.restfb.scope.ScopeBuilder;
034import com.restfb.types.DebugTokenInfo;
035import com.restfb.types.DeviceCode;
036
037/**
038 * Specifies how a <a href="http://developers.facebook.com/docs/api">Facebook Graph API</a> client must operate.
039 * <p>
040 * If you'd like to...
041 * 
042 * <ul>
043 * <li>Fetch an object: use {@link #fetchObject(String, Class, Parameter...)} or
044 * {@link #fetchObjects(List, Class, Parameter...)}</li>
045 * <li>Fetch a connection: use {@link #fetchConnection(String, Class, Parameter...)}</li>
046 * <li>Execute operations in batch: use {@link #executeBatch(BatchRequest...)} or {@link #executeBatch(List, List)}</li>
047 * <li>Publish data: use {@link #publish(String, Class, Parameter...)} or
048 * {@link #publish(String, Class, BinaryAttachment, Parameter...)}</li>
049 * <li>Delete an object: use {@link #deleteObject(String, Parameter...)}</li>
050 * </ul>
051 * 
052 * <p>
053 * You may also perform some common access token operations. If you'd like to...
054 * 
055 * <ul>
056 * <li>Extend the life of an access token: use {@link #obtainExtendedAccessToken(String, String, String)}</li>
057 * <li>Obtain an access token for use on behalf of an application instead of a user, use
058 * {@link #obtainAppAccessToken(String, String)}.</li>
059 * <li>Convert old-style session keys to OAuth access tokens: use
060 * {@link #convertSessionKeysToAccessTokens(String, String, String...)}</li>
061 * <li>Verify and extract data from a signed request: use {@link #parseSignedRequest(String, String, Class)}</li>
062 * </ul>
063 * 
064 * @author <a href="http://restfb.com">Mark Allen</a>
065 * @author Scott Hernandez
066 * @author Mattia Tommasone
067 * @author <a href="http://ex-nerd.com">Chris Petersen</a>
068 * @author Josef Gierbl
069 * @author Broc Seib
070 */
071public interface FacebookClient {
072  /**
073   * Fetches a single <a href="http://developers.facebook.com/docs/reference/api/">Graph API object</a>, mapping the
074   * result to an instance of {@code objectType}.
075   * 
076   * @param <T>
077   *          Java type to map to.
078   * @param object
079   *          ID of the object to fetch, e.g. {@code "me"}.
080   * @param objectType
081   *          Object type token.
082   * @param parameters
083   *          URL parameters to include in the API call (optional).
084   * @return An instance of type {@code objectType} which contains the requested object's data.
085   * @throws FacebookException
086   *           If an error occurs while performing the API call.
087   */
088  <T> T fetchObject(String object, Class<T> objectType, Parameter... parameters);
089
090  /**
091   * creates a new <code>FacebookClient</code> from a old one.
092   * <p>
093   * App secret and and api version are taken from the original client.
094   *
095   * @param accessToken
096   *          this accesstoken is used for the new client
097   * @return a new Facebookclient
098   */
099  FacebookClient createClientWithAccessToken(String accessToken);
100
101  /**
102   * Fetches multiple <a href="http://developers.facebook.com/docs/reference/api/">Graph API objects</a> in a single
103   * call, mapping the results to an instance of {@code objectType}.
104   * <p>
105   * You'll need to write your own container type ({@code objectType}) to hold the results. See
106   * <a href="http://restfb.com">http://restfb.com</a> for an example of how to do this.
107   * 
108   * @param <T>
109   *          Java type to map to.
110   * @param ids
111   *          IDs of the objects to fetch, e.g. {@code "me", "arjun"}.
112   * @param objectType
113   *          Object type token.
114   * @param parameters
115   *          URL parameters to include in the API call (optional).
116   * @return An instance of type {@code objectType} which contains the requested objects' data.
117   * @throws FacebookException
118   *           If an error occurs while performing the API call.
119   */
120  <T> T fetchObjects(List<String> ids, Class<T> objectType, Parameter... parameters);
121
122  /**
123   * Fetches a Graph API {@code Connection} type, mapping the result to an instance of {@code connectionType}.
124   * 
125   * @param <T>
126   *          Java type to map to.
127   * @param connection
128   *          The name of the connection, e.g. {@code "me/feed"}.
129   * @param connectionType
130   *          Connection type token.
131   * @param parameters
132   *          URL parameters to include in the API call (optional).
133   * @return An instance of type {@code connectionType} which contains the requested Connection's data.
134   * @throws FacebookException
135   *           If an error occurs while performing the API call.
136   */
137  <T> Connection<T> fetchConnection(String connection, Class<T> connectionType, Parameter... parameters);
138
139  /**
140   * Fetches a previous/next page of a Graph API {@code Connection} type, mapping the result to an instance of
141   * {@code connectionType}.
142   * 
143   * @param <T>
144   *          Java type to map to.
145   * @param connectionPageUrl
146   *          The URL of the connection page to fetch, usually retrieved via {@link Connection#getPreviousPageUrl()} or
147   *          {@link Connection#getNextPageUrl()}.
148   * @param connectionType
149   *          Connection type token.
150   * @return An instance of type {@code connectionType} which contains the requested Connection's data.
151   * @throws FacebookException
152   *           If an error occurs while performing the API call.
153   */
154  <T> Connection<T> fetchConnectionPage(String connectionPageUrl, Class<T> connectionType);
155
156  /**
157   * Executes operations as a batch using the <a href="https://developers.facebook.com/docs/reference/api/batch/">Batch
158   * API</a>.
159   * 
160   * @param batchRequests
161   *          The operations to execute.
162   * @return The execution results in the order in which the requests were specified.
163   */
164  List<BatchResponse> executeBatch(BatchRequest... batchRequests);
165
166  /**
167   * Executes operations as a batch using the <a href="https://developers.facebook.com/docs/reference/api/batch/">Batch
168   * API</a>.
169   * 
170   * @param batchRequests
171   *          The operations to execute.
172   * @return The execution results in the order in which the requests were specified.
173   */
174  List<BatchResponse> executeBatch(List<BatchRequest> batchRequests);
175
176  /**
177   * Executes operations as a batch with binary attachments using the
178   * <a href="https://developers.facebook.com/docs/reference/api/batch/">Batch API</a>.
179   * 
180   * @param batchRequests
181   *          The operations to execute.
182   * @param binaryAttachments
183   *          Binary attachments referenced by the batch requests.
184   * @return The execution results in the order in which the requests were specified.
185   * @since 1.6.5
186   */
187  List<BatchResponse> executeBatch(List<BatchRequest> batchRequests, List<BinaryAttachment> binaryAttachments);
188
189  /**
190   * Performs a <a href="http://developers.facebook.com/docs/api#publishing">Graph API publish</a> operation on the
191   * given {@code connection}, mapping the result to an instance of {@code objectType}.
192   * 
193   * @param <T>
194   *          Java type to map to.
195   * @param connection
196   *          The Connection to publish to.
197   * @param objectType
198   *          Object type token.
199   * @param parameters
200   *          URL parameters to include in the API call.
201   * @return An instance of type {@code objectType} which contains the Facebook response to your publish request.
202   * @throws FacebookException
203   *           If an error occurs while performing the API call.
204   */
205  <T> T publish(String connection, Class<T> objectType, Parameter... parameters);
206
207  /**
208   * Performs a <a href="http://developers.facebook.com/docs/api#publishing">Graph API publish</a> operation on the
209   * given {@code connection} and includes some files - photos, for example - in the publish request, and mapping the
210   * result to an instance of {@code objectType}.
211   * 
212   * @param <T>
213   *          Java type to map to.
214   * @param connection
215   *          The Connection to publish to.
216   * @param objectType
217   *          Object type token.
218   * @param binaryAttachments
219   *          The files to include in the publish request.
220   * @param parameters
221   *          URL parameters to include in the API call.
222   * @return An instance of type {@code objectType} which contains the Facebook response to your publish request.
223   * @throws FacebookException
224   *           If an error occurs while performing the API call.
225   */
226  <T> T publish(String connection, Class<T> objectType, List<BinaryAttachment> binaryAttachments,
227      Parameter... parameters);
228
229  /**
230   * Performs a <a href="http://developers.facebook.com/docs/api#publishing">Graph API publish</a> operation on the
231   * given {@code connection} and includes a file - a photo, for example - in the publish request, and mapping the
232   * result to an instance of {@code objectType}.
233   * 
234   * @param <T>
235   *          Java type to map to.
236   * @param connection
237   *          The Connection to publish to.
238   * @param objectType
239   *          Object type token.
240   * @param binaryAttachment
241   *          The file to include in the publish request.
242   * @param parameters
243   *          URL parameters to include in the API call.
244   * @return An instance of type {@code objectType} which contains the Facebook response to your publish request.
245   * @throws FacebookException
246   *           If an error occurs while performing the API call.
247   */
248  <T> T publish(String connection, Class<T> objectType, BinaryAttachment binaryAttachment, Parameter... parameters);
249
250  /**
251   * Performs a <a href="http://developers.facebook.com/docs/api#publishing">Graph API publish</a> operation on the
252   * given {@code connection} and includes special body in the publish request, and mapping the result to an instance of
253   * {@code objectType}.
254   *
255   * @param <T>
256   *          Java type to map to.
257   * @param connection
258   *          The Connection to publish to.
259   * @param objectType
260   *          Object type token.
261   * @param body
262   *          The body used in the POST request.
263   * @param parameters
264   *          URL parameters to include in the API call.
265   * @return An instance of type {@code objectType} which contains the Facebook response to your publish request.
266   * @throws FacebookException
267   *           If an error occurs while performing the API call.
268   */
269  <T> T publish(String connection, Class<T> objectType, Body body, Parameter... parameters);
270
271  /**
272   * Performs a <a href="http://developers.facebook.com/docs/api#deleting">Graph API delete</a> operation on the given
273   * {@code object}.
274   * 
275   * @param object
276   *          The ID of the object to delete.
277   * @param parameters
278   *          URL parameters to include in the API call.
279   * @return {@code true} if Facebook indicated that the object was successfully deleted, {@code false} otherwise.
280   * @throws FacebookException
281   *           If an error occurred while attempting to delete the object.
282   */
283  boolean deleteObject(String object, Parameter... parameters);
284
285  /**
286   * Converts an arbitrary number of {@code sessionKeys} to OAuth access tokens.
287   * <p>
288   * See the <a href="http://developers.facebook.com/docs/guides/upgrade">Facebook Platform Upgrade Guide</a> for
289   * details on how this process works and why you should convert your application's session keys if you haven't
290   * already.
291   * 
292   * @param appId
293   *          A Facebook application ID.
294   * @param secretKey
295   *          A Facebook application secret key.
296   * @param sessionKeys
297   *          The Old REST API session keys to be converted to OAuth access tokens.
298   * @return A list of access tokens ordered to correspond to the {@code sessionKeys} argument list.
299   * @throws FacebookException
300   *           If an error occurs while attempting to convert the session keys to API keys.
301   * @since 1.6
302   */
303  List<AccessToken> convertSessionKeysToAccessTokens(String appId, String secretKey, String... sessionKeys);
304
305  /**
306   * Obtains an access token which can be used to perform Graph API operations on behalf of a user.
307   * <p>
308   * See <a href="https://developers.facebook.com/docs/facebook-login/access-tokens">Access Tokens</a>.
309   *
310   * @param appId
311   *          The ID of the app for which you'd like to obtain an access token.
312   * @param appSecret
313   *          The secret for the app for which you'd like to obtain an access token.
314   * @param redirectUri
315   *          The redirect URI which was used to obtain the {@code verificationCode}.
316   * @param verificationCode
317   *          The verification code in the Graph API callback to the redirect URI.
318   * @return The access token for the user identified by {@code appId}, {@code appSecret}, {@code redirectUri} and
319   *         {@code verificationCode}.
320   * @throws FacebookException
321   *           If an error occurs while attempting to obtain an access token.
322   * @since 1.8.0
323   */
324  AccessToken obtainUserAccessToken(String appId, String appSecret, String redirectUri, String verificationCode);
325
326  /**
327   * Obtains an access token which can be used to perform Graph API operations on behalf of an application instead of a
328   * user.
329   * <p>
330   * See <a href="https://developers.facebook.com/docs/authentication/applications/" >Facebook's authenticating as an
331   * app documentation</a>.
332   * 
333   * @param appId
334   *          The ID of the app for which you'd like to obtain an access token.
335   * @param appSecret
336   *          The secret for the app for which you'd like to obtain an access token.
337   * @return The access token for the application identified by {@code appId} and {@code appSecret}.
338   * @throws FacebookException
339   *           If an error occurs while attempting to obtain an access token.
340   * @since 1.6.10
341   */
342  AccessToken obtainAppAccessToken(String appId, String appSecret);
343
344  /**
345   * Obtains an extended access token for the given existing, non-expired, short-lived access_token.
346   * <p>
347   * See <a href="https://developers.facebook.com/roadmap/offline-access-removal/#extend_token">Facebook's extend access
348   * token documentation</a>.
349   * 
350   * @param appId
351   *          The ID of the app for which you'd like to obtain an extended access token.
352   * @param appSecret
353   *          The secret for the app for which you'd like to obtain an extended access token.
354   * @param accessToken
355   *          The non-expired, short-lived access token to extend.
356   * @return An extended access token for the given {@code accessToken}.
357   * @throws FacebookException
358   *           If an error occurs while attempting to obtain an extended access token.
359   * @since 1.6.10
360   */
361  AccessToken obtainExtendedAccessToken(String appId, String appSecret, String accessToken);
362
363  /**
364   * Generates an {@code appsecret_proof} value.
365   * <p>
366   * See <a href="https://developers.facebook.com/docs/graph-api/securing-requests">Facebook's 'securing requests'
367   * documentation</a> for more info.
368   * 
369   * @param accessToken
370   *          The access token required to generate the {@code appsecret_proof} value.
371   * @param appSecret
372   *          The secret for the app for which you'd like to generate the {@code appsecret_proof} value.
373   * @return A hex-encoded SHA256 hash as a {@code String}.
374   * @throws IllegalStateException
375   *           If creating the {@code appsecret_proof} fails.
376   * @since 1.6.13
377   */
378  String obtainAppSecretProof(String accessToken, String appSecret);
379
380  /**
381   * Convenience method which invokes {@link #obtainExtendedAccessToken(String, String, String)} with the current access
382   * token.
383   * 
384   * @param appId
385   *          The ID of the app for which you'd like to obtain an extended access token.
386   * @param appSecret
387   *          The secret for the app for which you'd like to obtain an extended access token.
388   * @return An extended access token for the given {@code accessToken}.
389   * @throws FacebookException
390   *           If an error occurs while attempting to obtain an extended access token.
391   * @throws IllegalStateException
392   *           If this instance was not constructed with an access token.
393   * @since 1.6.10
394   */
395  AccessToken obtainExtendedAccessToken(String appId, String appSecret);
396
397  /**
398   * Obtain a refreshed Instagram extended access token.
399   *
400   * <p>
401   * This method is used to refresh an existing Instagram extended access token. Extended access tokens expire after a
402   * certain period of time, and this method allows you to obtain a new one using the refresh token provided with the
403   * original extended access token.
404   *
405   * @return A new {@link AccessToken} object containing the refreshed access token, expiration time, and token type.
406   * @throws FacebookResponseContentException
407   *           If the response from the Facebook API cannot be parsed or if the access token cannot be extracted from
408   *           the response.
409   */
410  AccessToken obtainRefreshedExtendedAccessToken();
411
412  /**
413   * Parses a signed request and verifies it against your App Secret.
414   * <p>
415   * See <a href="http://developers.facebook.com/docs/howtos/login/signed-request/">Facebook's signed request
416   * documentation</a>.
417   * 
418   * @param signedRequest
419   *          The signed request to parse.
420   * @param appSecret
421   *          The secret for the app that can read this signed request.
422   * @param objectType
423   *          Object type token.
424   * @param <T>
425   *          class of objectType
426   * @return An instance of type {@code objectType} which contains the decoded object embedded within
427   *         {@code signedRequest}.
428   * @throws FacebookSignedRequestParsingException
429   *           If an error occurs while trying to process {@code signedRequest}.
430   * @throws FacebookSignedRequestVerificationException
431   *           If {@code signedRequest} fails verification against {@code appSecret}.
432   * @since 1.6.13
433   */
434  <T> T parseSignedRequest(String signedRequest, String appSecret, Class<T> objectType);
435
436  /**
437   * Method to initialize the device access token generation.
438   * <p>
439   * You receive a {@link DeviceCode} instance and have to show the user the {@link DeviceCode#getVerificationUri()} and
440   * the {@link DeviceCode#getUserCode()}. The user have to enter the user code at the verification url.
441   * <p>
442   * Save the {@link DeviceCode#getCode()} to use it later, when polling Facebook with the
443   * {@link #obtainDeviceAccessToken(java.lang.String)} method.
444   *
445   * @param scope
446   *          List of Permissions to request from the person using your app.
447   * @return Instance of {@code DeviceCode} including the information to obtain the Device access token
448   */
449  DeviceCode fetchDeviceCode(ScopeBuilder scope);
450
451  /**
452   * Method to poll Facebook and fetch the Device Access Token.
453   * <p>
454   * You have to use this method to check if the user confirms the authorization.
455   * <p>
456   * {@link FacebookOAuthException} can be thrown if the authorization is declined or still pending.
457   *
458   * @param code
459   *          The device
460   * @return An extended access token for the given {@link AccessToken}.
461   * @throws com.restfb.exception.devicetoken.FacebookDeviceTokenCodeExpiredException
462   *           the {@link DeviceCode#getCode()} is expired, please fetch a new {@link DeviceCode}.
463   * @throws com.restfb.exception.devicetoken.FacebookDeviceTokenPendingException
464   *           the user has not finished the authorisation process, yet. Please poll again later.
465   * @throws com.restfb.exception.devicetoken.FacebookDeviceTokenDeclinedException
466   *           the user declined the authorisation. You have to handle this problem.
467   * @throws com.restfb.exception.devicetoken.FacebookDeviceTokenSlowdownException
468   *           you tried too often to fetch the device access token. You have to use a larger interval
469   * @since 1.12.0
470   */
471  AccessToken obtainDeviceAccessToken(String code) throws FacebookDeviceTokenCodeExpiredException,
472      FacebookDeviceTokenPendingException, FacebookDeviceTokenDeclinedException, FacebookDeviceTokenSlowdownException;
473
474  /**
475   * <p>
476   * When working with access tokens, you may need to check what information is associated with them, such as its user
477   * or expiry. To get this information you can use the debug tool in the developer site, or you can use this function.
478   * </p>
479   * 
480   * <p>
481   * You must instantiate your FacebookClient using your App Access Token, or a valid User Access Token from a developer
482   * of the app.
483   * </p>
484   * 
485   * <p>
486   * Note that if your app is set to Native/Desktop in the Advanced settings of your App Dashboard, the underlying
487   * GraphAPI endpoint will not work with your app token unless you change the "App Secret in Client" setting to NO. If
488   * you do not see this setting, make sure your "App Type" is set to Native/Desktop and then press the save button at
489   * the bottom of the page. This will not affect apps set to Web.
490   * </p>
491   * 
492   * <p>
493   * The response of the API call is a JSON array containing data and a map of fields. For example:
494   * </p>
495   * 
496   * <pre>
497   * {@code
498   * {
499   *     "data": {
500   *         "app_id": 138483919580948, 
501   *         "application": "Social Cafe", 
502   *         "expires_at": 1352419328, 
503   *         "is_valid": true, 
504   *         "issued_at": 1347235328, 
505   *         "metadata": {
506   *             "sso": "iphone-safari"
507   *         }, 
508   *         "scopes": [
509   *             "email", 
510   *             "publish_actions"
511   *         ], 
512   *         "user_id": 1207059
513   *     }
514   * }
515   * }
516   * </pre>
517   * 
518   * <p>
519   * Note that the {@code issued_at} field is not returned for short-lived access tokens.
520   * </p>
521   * 
522   * <p>
523   * See <a href="https://developers.facebook.com/docs/howtos/login/debugging-access-tokens/"> Debugging an Access
524   * Token</a>
525   * </p>
526   * 
527   * @param inputToken
528   *          The Access Token to debug.
529   * 
530   * @return A JsonObject containing the debug information for the accessToken.
531   * @since 1.6.13
532   */
533  DebugTokenInfo debugToken(String inputToken);
534
535  /**
536   * Gets the {@code JsonMapper} used to convert Facebook JSON to Java objects.
537   * 
538   * @return The {@code JsonMapper} used to convert Facebook JSON to Java objects.
539   * @since 1.6.7
540   */
541  JsonMapper getJsonMapper();
542
543  /**
544   * Gets the {@code WebRequestor} used to talk to the Facebook API endpoints.
545   * 
546   * @return The {@code WebRequestor} used to talk to the Facebook API endpoints.
547   * @since 1.6.7
548   */
549  WebRequestor getWebRequestor();
550
551  /**
552   * generates an logout url
553   * 
554   * @param next
555   *          may be null, url the webpage should redirect after logout
556   * @return the logout url
557   * @since 1.9.0
558   */
559  String getLogoutUrl(String next);
560
561  /**
562   * generates the login dialog url
563   *
564   * @param appId
565   *          The ID of your app, found in your app's dashboard.
566   * @param redirectUri
567   *          The URL that you want to redirect the person logging in back to. This URL will capture the response from
568   *          the Login Dialog. If you are using this in a webview within a desktop app, this must be set to
569   *          <code>https://www.facebook.com/connect/login_success.html</code>.
570   * @param scope
571   *          List of Permissions to request from the person using your app.
572   * @param state
573   *         The state parameter is used to prevent CSRF attacks.
574   * @param parameters
575   *          List of additional parameters
576   * @since 1.9.0
577   * @return the login dialog url
578   */
579  String getLoginDialogUrl(String appId, String redirectUri, ScopeBuilder scope, String state, Parameter... parameters);
580
581  /**
582   * generates the login dialog url
583   * 
584   * @param appId
585   *          The ID of your app, found in your app's dashboard.
586   * @param redirectUri
587   *          The URL that you want to redirect the person logging in back to. This URL will capture the response from
588   *          the Login Dialog. If you are using this in a webview within a desktop app, this must be set to
589   *          <code>https://www.facebook.com/connect/login_success.html</code>.
590   * @param scope
591   *          List of Permissions to request from the person using your app.
592   * @param additionalParameters
593   *          List of additional parameters
594   * @since 1.9.0
595   * @return the login dialog url
596   */
597  String getLoginDialogUrl(String appId, String redirectUri, ScopeBuilder scope, Parameter... additionalParameters);
598
599}