com.drismo.facebook
Class Facebook

java.lang.Object
  extended by com.drismo.facebook.Facebook

public class Facebook
extends java.lang.Object

Main Facebook object for interacting with the Facebook developer API. Provides methods to log in and log out a user, make requests using the REST and Graph APIs, and start user interface interactions with the API (such as pop-ups promoting for credentials, permissions, stream posts, etc.)


Nested Class Summary
static interface Facebook.DialogListener
          Callback interface for dialog requests.
 
Field Summary
static java.lang.String CANCEL_URI
           
private static int DEFAULT_AUTH_ACTIVITY_CODE
           
protected static java.lang.String DIALOG_BASE_URL
           
static java.lang.String EXPIRES
           
static java.lang.String FB_APP_SIGNATURE
           
static int FORCE_DIALOG_AUTH
           
protected static java.lang.String GRAPH_BASE_URL
           
private static java.lang.String LOGIN
           
private  long mAccessExpires
           
private  java.lang.String mAccessToken
           
private  java.lang.String mAppId
           
private  android.app.Activity mAuthActivity
           
private  int mAuthActivityCode
           
private  Facebook.DialogListener mAuthDialogListener
           
private  java.lang.String[] mAuthPermissions
           
static java.lang.String REDIRECT_URI
           
protected static java.lang.String RESTSERVER_URL
           
static java.lang.String SINGLE_SIGN_ON_DISABLED
           
static java.lang.String TOKEN
           
 
Constructor Summary
Facebook(java.lang.String appId)
          Constructor for Facebook object.
 
Method Summary
 void authorize(android.app.Activity activity, Facebook.DialogListener listener)
          Default authorize method.
 void authorize(android.app.Activity activity, java.lang.String[] permissions, Facebook.DialogListener listener)
          Authorize method that grants custom permissions.
 void authorize(android.app.Activity activity, java.lang.String[] permissions, int activityCode, Facebook.DialogListener listener)
          Full authorize method.
 void authorizeCallback(int requestCode, int resultCode, android.content.Intent data)
          IMPORTANT: This method must be invoked at the top of the calling activity's onActivityResult() function or Facebook authentication will not function properly!
 void dialog(android.content.Context context, java.lang.String action, android.os.Bundle parameters, Facebook.DialogListener listener)
          Generate a UI dialog for the request action in the given Android context with the provided parameters.
 void dialog(android.content.Context context, java.lang.String action, Facebook.DialogListener listener)
          Generate a UI dialog for the request action in the given Android context.
 long getAccessExpires()
          Retrieve the current session's expiration time (in milliseconds since Unix epoch), or 0 if the session doesn't expire or doesn't exist.
 java.lang.String getAccessToken()
          Retrieve the OAuth 2.0 access token for API access: treat with care.
 java.lang.String getAppId()
           
 boolean isSessionValid()
           
 java.lang.String logout(android.content.Context context)
          Invalidate the current user session by removing the access token in memory, clearing the browser cookie, and calling auth.expireSession through the API.
 java.lang.String request(android.os.Bundle parameters)
          Make a request to Facebook's old (pre-graph) API with the given parameters.
 java.lang.String request(java.lang.String graphPath)
          Make a request to the Facebook Graph API without any parameters.
 java.lang.String request(java.lang.String graphPath, android.os.Bundle parameters)
          Make a request to the Facebook Graph API with the given string parameters using an HTTP GET (default method).
 java.lang.String request(java.lang.String graphPath, android.os.Bundle params, java.lang.String httpMethod)
          Synchronously make a request to the Facebook Graph API with the given HTTP method and string parameters.
 void setAccessExpires(long time)
          Set the current session's expiration time (in milliseconds since Unix epoch), or 0 if the session doesn't expire.
 void setAccessExpiresIn(java.lang.String expiresIn)
          Set the current session's duration (in seconds since Unix epoch).
 void setAccessToken(java.lang.String token)
          Set the OAuth 2.0 access token for API access.
 void setAppId(java.lang.String appId)
           
private  void startDialogAuth(android.app.Activity activity, java.lang.String[] permissions)
          Internal method to handle dialog-based authentication backend for authorize().
private  boolean startSingleSignOn(android.app.Activity activity, java.lang.String applicationId, java.lang.String[] permissions, int activityCode)
          Internal method to handle single sign-on backend for authorize().
private  boolean validateAppSignatureForIntent(android.app.Activity activity, android.content.Intent intent)
          Query the signature for the application that would be invoked by the given intent and verify that it matches the FB application's signature.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

REDIRECT_URI

public static final java.lang.String REDIRECT_URI
See Also:
Constant Field Values

CANCEL_URI

public static final java.lang.String CANCEL_URI
See Also:
Constant Field Values

TOKEN

public static final java.lang.String TOKEN
See Also:
Constant Field Values

EXPIRES

public static final java.lang.String EXPIRES
See Also:
Constant Field Values

SINGLE_SIGN_ON_DISABLED

public static final java.lang.String SINGLE_SIGN_ON_DISABLED
See Also:
Constant Field Values

FORCE_DIALOG_AUTH

public static final int FORCE_DIALOG_AUTH
See Also:
Constant Field Values

LOGIN

private static final java.lang.String LOGIN
See Also:
Constant Field Values

DEFAULT_AUTH_ACTIVITY_CODE

private static final int DEFAULT_AUTH_ACTIVITY_CODE
See Also:
Constant Field Values

DIALOG_BASE_URL

protected static java.lang.String DIALOG_BASE_URL

GRAPH_BASE_URL

protected static java.lang.String GRAPH_BASE_URL

RESTSERVER_URL

protected static java.lang.String RESTSERVER_URL

mAccessToken

private java.lang.String mAccessToken

mAccessExpires

private long mAccessExpires

mAppId

private java.lang.String mAppId

mAuthActivity

private android.app.Activity mAuthActivity

mAuthPermissions

private java.lang.String[] mAuthPermissions

mAuthActivityCode

private int mAuthActivityCode

mAuthDialogListener

private Facebook.DialogListener mAuthDialogListener

FB_APP_SIGNATURE

public static final java.lang.String FB_APP_SIGNATURE
See Also:
Constant Field Values
Constructor Detail

Facebook

public Facebook(java.lang.String appId)
Constructor for Facebook object.

Parameters:
appId - Your Facebook application ID. Found at www.facebook.com/developers/apps.php.
Method Detail

authorize

public void authorize(android.app.Activity activity,
                      Facebook.DialogListener listener)
Default authorize method. Grants only basic permissions. See authorize() below for @params.


authorize

public void authorize(android.app.Activity activity,
                      java.lang.String[] permissions,
                      Facebook.DialogListener listener)
Authorize method that grants custom permissions. See authorize() below for @params.


authorize

public void authorize(android.app.Activity activity,
                      java.lang.String[] permissions,
                      int activityCode,
                      Facebook.DialogListener listener)
Full authorize method. Starts either an Activity or a dialog which prompts the user to log in to Facebook and grant the requested permissions to the given application. This method will, when possible, use Facebook's single sign-on for Android to obtain an access token. This involves proxying a call through the Facebook for Android stand-alone application, which will handle the authentication flow, and return an OAuth access token for making API calls. Because this process will not be available for all users, if single sign-on is not possible, this method will automatically fall back to the OAuth 2.0 User-Agent flow. In this flow, the user credentials are handled by Facebook in an embedded WebView, not by the client application. As such, the dialog makes a network request and renders HTML content rather than a native UI. The access token is retrieved from a redirect to a special URL that the WebView handles. Note that User credentials could be handled natively using the OAuth 2.0 Username and Password Flow, but this is not supported by this SDK. See http://developers.facebook.com/docs/authentication/ and http://wiki.oauth.net/OAuth-2 for more details. Note that this method is asynchronous and the callback will be invoked in the original calling thread (not in a background thread). Also note that requests may be made to the API without calling authorize first, in which case only public information is returned. IMPORTANT: Note that single sign-on authentication will not function correctly if you do not include a call to the authorizeCallback() method in your onActivityResult() function! Please see below for more information. single sign-on may be disabled by passing FORCE_DIALOG_AUTH as the activityCode parameter in your call to authorize().

Parameters:
activity - The Android activity in which we want to display the authorization dialog.
applicationId - The Facebook application identifier e.g. "350685531728"
permissions - A list of permissions required for this application: e.g. "read_stream", "publish_stream", "offline_access", etc. see http://developers.facebook.com/docs/authentication/permissions This parameter should not be null -- if you do not require any permissions, then pass in an empty String array.
activityCode - Single sign-on requires an activity result to be called back to the client application -- if you are waiting on other activities to return data, pass a custom activity code here to avoid collisions. If you would like to force the use of legacy dialog-based authorization, pass FORCE_DIALOG_AUTH for this parameter. Otherwise just omit this parameter and Facebook will use a suitable default. See http://developer.facebook.com/reference/facebook/ app/Activity.html for more information.
listener - Callback interface for notifying the calling application when the authentication dialog has completed, failed, or been canceled.

startSingleSignOn

private boolean startSingleSignOn(android.app.Activity activity,
                                  java.lang.String applicationId,
                                  java.lang.String[] permissions,
                                  int activityCode)
Internal method to handle single sign-on backend for authorize().

Parameters:
activity - The Android Activity that will parent the ProxyAuth Activity.
applicationId - The Facebook application identifier.
permissions - A list of permissions required for this application. If you do not require any permissions, pass an empty String array.
activityCode - Activity code to uniquely identify the result Intent in the callback.

validateAppSignatureForIntent

private boolean validateAppSignatureForIntent(android.app.Activity activity,
                                              android.content.Intent intent)
Query the signature for the application that would be invoked by the given intent and verify that it matches the FB application's signature.

Parameters:
activity -
intent -
validSignature -
Returns:
true if the app's signature matches the expected signature.

startDialogAuth

private void startDialogAuth(android.app.Activity activity,
                             java.lang.String[] permissions)
Internal method to handle dialog-based authentication backend for authorize().

Parameters:
activity - The Android Activity that will parent the auth dialog.
applicationId - The Facebook application identifier.
permissions - A list of permissions required for this application. If you do not require any permissions, pass an empty String array.

authorizeCallback

public void authorizeCallback(int requestCode,
                              int resultCode,
                              android.content.Intent data)
IMPORTANT: This method must be invoked at the top of the calling activity's onActivityResult() function or Facebook authentication will not function properly! If your calling activity does not currently implement onActivityResult(), you must implement it and include a call to this method if you intend to use the authorize() method in this SDK. For more information, see http://developer.facebook.com/reference/facebook/app/ Activity.html#onActivityResult(int, int, facebook.content.Intent)


logout

public java.lang.String logout(android.content.Context context)
                        throws java.net.MalformedURLException,
                               java.io.IOException
Invalidate the current user session by removing the access token in memory, clearing the browser cookie, and calling auth.expireSession through the API. Note that this method blocks waiting for a network response, so do not call it in a UI thread.

Parameters:
context - The Android context in which the logout should be called: it should be the same context in which the login occurred in order to clear any stored cookies
Returns:
JSON string representation of the auth.expireSession response ("true" if successful)
Throws:
java.io.IOException
java.net.MalformedURLException

request

public java.lang.String request(android.os.Bundle parameters)
                         throws java.net.MalformedURLException,
                                java.io.IOException
Make a request to Facebook's old (pre-graph) API with the given parameters. One of the parameter keys must be "method" and its value should be a valid REST server API method. See http://developers.facebook.com/docs/reference/rest/ Note that this method blocks waiting for a network response, so do not call it in a UI thread. Example: Bundle parameters = new Bundle(); parameters.putString("method", "auth.expireSession"); String response = request(parameters);

Parameters:
parameters - Key-value pairs of parameters to the request. Refer to the documentation: one of the parameters must be "method".
Returns:
JSON string representation of the response
Throws:
java.io.IOException - if a network error occurs
java.net.MalformedURLException - if accessing an invalid endpoint
java.lang.IllegalArgumentException - if one of the parameters is not "method"

request

public java.lang.String request(java.lang.String graphPath)
                         throws java.net.MalformedURLException,
                                java.io.IOException
Make a request to the Facebook Graph API without any parameters. See http://developers.facebook.com/docs/api Note that this method blocks waiting for a network response, so do not call it in a UI thread.

Parameters:
graphPath - Path to resource in the Facebook graph, e.g., to fetch data about the currently logged authenticated user, provide "me", which will fetch http://graph.facebook.com/me
Returns:
JSON string representation of the response
Throws:
java.io.IOException
java.net.MalformedURLException

request

public java.lang.String request(java.lang.String graphPath,
                                android.os.Bundle parameters)
                         throws java.net.MalformedURLException,
                                java.io.IOException
Make a request to the Facebook Graph API with the given string parameters using an HTTP GET (default method). See http://developers.facebook.com/docs/api Note that this method blocks waiting for a network response, so do not call it in a UI thread.

Parameters:
graphPath - Path to resource in the Facebook graph, e.g., to fetch data about the currently logged authenticated user, provide "me", which will fetch http://graph.facebook.com/me
parameters - key-value string parameters, e.g. the path "search" with parameters "q" : "facebook" would produce a query for the following graph resource: https://graph.facebook.com/search?q=facebook
Returns:
JSON string representation of the response
Throws:
java.io.IOException
java.net.MalformedURLException

request

public java.lang.String request(java.lang.String graphPath,
                                android.os.Bundle params,
                                java.lang.String httpMethod)
                         throws java.io.FileNotFoundException,
                                java.net.MalformedURLException,
                                java.io.IOException
Synchronously make a request to the Facebook Graph API with the given HTTP method and string parameters. Note that binary data parameters (e.g. pictures) are not yet supported by this helper function. See http://developers.facebook.com/docs/api Note that this method blocks waiting for a network response, so do not call it in a UI thread.

Parameters:
graphPath - Path to resource in the Facebook graph, e.g., to fetch data about the currently logged authenticated user, provide "me", which will fetch http://graph.facebook.com/me
params - Key-value string parameters, e.g. the path "search" with parameters {"q" : "facebook"} would produce a query for the following graph resource: https://graph.facebook.com/search?q=facebook
httpMethod - http verb, e.g. "GET", "POST", "DELETE"
Returns:
JSON string representation of the response
Throws:
java.io.IOException
java.net.MalformedURLException
java.io.FileNotFoundException

dialog

public void dialog(android.content.Context context,
                   java.lang.String action,
                   Facebook.DialogListener listener)
Generate a UI dialog for the request action in the given Android context. Note that this method is asynchronous and the callback will be invoked in the original calling thread (not in a background thread).

Parameters:
context - The Android context in which we will generate this dialog.
action - String representation of the desired method: e.g. "login", "stream.publish", ...
listener - Callback interface to notify the application when the dialog has completed.

dialog

public void dialog(android.content.Context context,
                   java.lang.String action,
                   android.os.Bundle parameters,
                   Facebook.DialogListener listener)
Generate a UI dialog for the request action in the given Android context with the provided parameters. Note that this method is asynchronous and the callback will be invoked in the original calling thread (not in a background thread).

Parameters:
context - The Android context in which we will generate this dialog.
action - String representation of the desired method: e.g. "feed" ...
parameters - String key-value pairs to be passed as URL parameters.
listener - Callback interface to notify the application when the dialog has completed.

isSessionValid

public boolean isSessionValid()
Returns:
boolean - whether this object has an non-expired session token

getAccessToken

public java.lang.String getAccessToken()
Retrieve the OAuth 2.0 access token for API access: treat with care. Returns null if no session exists.

Returns:
String - access token

getAccessExpires

public long getAccessExpires()
Retrieve the current session's expiration time (in milliseconds since Unix epoch), or 0 if the session doesn't expire or doesn't exist.

Returns:
long - session expiration time

setAccessToken

public void setAccessToken(java.lang.String token)
Set the OAuth 2.0 access token for API access.

Parameters:
token - - access token

setAccessExpires

public void setAccessExpires(long time)
Set the current session's expiration time (in milliseconds since Unix epoch), or 0 if the session doesn't expire.

Parameters:
time - - timestamp in milliseconds

setAccessExpiresIn

public void setAccessExpiresIn(java.lang.String expiresIn)
Set the current session's duration (in seconds since Unix epoch).

Parameters:
expiresIn - - duration in seconds

getAppId

public java.lang.String getAppId()

setAppId

public void setAppId(java.lang.String appId)