com.facebook
Class Session

java.lang.Object
  extended by com.facebook.Session
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
TestSession

public class Session
extends Object
implements Serializable

Session is used to authenticate a user and manage the user's session with Facebook.

Sessions must be opened before they can be used to make a Request. When a Session is created, it attempts to initialize itself from a TokenCachingStrategy. Closing the session can optionally clear this cache. The Session lifecycle uses SessionState to indicate its state.

Instances of Session provide state change notification via a callback interface, StatusCallback.

See Also:
Serialized Form

Nested Class Summary
static class Session.AuthorizationRequest
          Base class for authorization requests Session.OpenRequest and Session.NewPermissionsRequest.
static class Session.Builder
          Builder class used to create a Session.
static class Session.NewPermissionsRequest
          A request to be used to request new permissions for a Session.
static class Session.OpenRequest
          A request used to open a Session.
static interface Session.StatusCallback
          Provides asynchronous notification of Session state changes.
 
Field Summary
static String ACTION_ACTIVE_SESSION_CLOSED
          The action used to indicate that the active session has been closed.
static String ACTION_ACTIVE_SESSION_OPENED
          The action used to indicate that the active session has been opened.
static String ACTION_ACTIVE_SESSION_SET
          The action used to indicate that the active session has been set.
static String ACTION_ACTIVE_SESSION_UNSET
          The action used to indicate that the active session has been set to null.
static String APPLICATION_ID_PROPERTY
          Session takes application id as a constructor parameter.
static int DEFAULT_AUTHORIZE_ACTIVITY_CODE
          The default activity code used for authorization.
static String TAG
          The logging tag used by Session.
static String WEB_VIEW_ERROR_CODE_KEY
          If Session authorization fails and provides a web view error code, the web view error code is stored in the Bundle returned from getAuthorizationBundle under this key.
static String WEB_VIEW_FAILING_URL_KEY
          If Session authorization fails and provides a failing url, the failing url is stored in the Bundle returned from getAuthorizationBundle under this key.
 
Constructor Summary
Session(Context currentContext)
          Initializes a new Session with the specified context.
 
Method Summary
 void addCallback(Session.StatusCallback callback)
          Adds a callback that will be called when the state of this Session changes.
 void close()
          Closes the local in-memory Session object, but does not clear the persisted token cache.
 void closeAndClearTokenInformation()
          Closes the local in-memory Session object and clears any persisted token cache related to the Session.
 boolean equals(Object otherObj)
           
 String getAccessToken()
          Returns the access token String.
static Session getActiveSession()
          Returns the current active Session, or null if there is none.
 String getApplicationId()
          Returns the application id associated with this Session.
 Bundle getAuthorizationBundle()
          Returns a Bundle containing data that was returned from Facebook during authorization.
 Date getExpirationDate()
           Returns the Date at which the current token will expire.
 List<String> getPermissions()
           Returns the list of permissions associated with the session.
 SessionState getState()
          Returns the current state of the Session.
 int hashCode()
           
 boolean isClosed()
           
 boolean isOpened()
          Returns a boolean indicating whether the session is opened.
 boolean onActivityResult(Activity currentActivity, int requestCode, int resultCode, Intent data)
          Provides an implementation for onActivityResult that updates the Session based on information returned during the authorization flow.
 void open(AccessToken accessToken, Session.StatusCallback callback)
          Opens a session based on an existing Facebook access token.
static Session openActiveSession(Activity activity, boolean allowLoginUI, Session.StatusCallback callback)
          If allowLoginUI is true, this will create a new Session, make it active, and open it.
static Session openActiveSession(Context context, Fragment fragment, boolean allowLoginUI, Session.StatusCallback callback)
          If allowLoginUI is true, this will create a new Session, make it active, and open it.
static Session openActiveSessionFromCache(Context context)
          Create a new Session, and if a token cache is available, open the Session and make it active without any user interaction.
static Session openActiveSessionWithAccessToken(Context context, AccessToken accessToken, Session.StatusCallback callback)
          Opens a session based on an existing Facebook access token, and also makes this session the currently active session.
 void openForPublish(Session.OpenRequest openRequest)
           Logs a user in to Facebook.
 void openForRead(Session.OpenRequest openRequest)
           Logs a user in to Facebook.
 void removeCallback(Session.StatusCallback callback)
          Removes a StatusCallback from this Session.
 void requestNewPublishPermissions(Session.NewPermissionsRequest newPermissionsRequest)
           Issues a request to add new publish or manage permissions to the Session.
 void requestNewReadPermissions(Session.NewPermissionsRequest newPermissionsRequest)
           Issues a request to add new read permissions to the Session.
static Session restoreSession(Context context, TokenCachingStrategy cachingStrategy, Session.StatusCallback callback, Bundle bundle)
          Restores the saved session from a Bundle, if any.
static void saveSession(Session session, Bundle bundle)
          Save the Session object into the supplied Bundle.
static void setActiveSession(Session session)
           Sets the current active Session.
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

TAG

public static final String TAG
The logging tag used by Session.


DEFAULT_AUTHORIZE_ACTIVITY_CODE

public static final int DEFAULT_AUTHORIZE_ACTIVITY_CODE
The default activity code used for authorization.

See Also:
open, Constant Field Values

WEB_VIEW_ERROR_CODE_KEY

public static final String WEB_VIEW_ERROR_CODE_KEY
If Session authorization fails and provides a web view error code, the web view error code is stored in the Bundle returned from getAuthorizationBundle under this key.

See Also:
Constant Field Values

WEB_VIEW_FAILING_URL_KEY

public static final String WEB_VIEW_FAILING_URL_KEY
If Session authorization fails and provides a failing url, the failing url is stored in the Bundle returned from getAuthorizationBundle under this key.

See Also:
Constant Field Values

ACTION_ACTIVE_SESSION_SET

public static final String ACTION_ACTIVE_SESSION_SET
The action used to indicate that the active session has been set. This should be used as an action in an IntentFilter and BroadcastReceiver registered with the LocalBroadcastManager.

See Also:
Constant Field Values

ACTION_ACTIVE_SESSION_UNSET

public static final String ACTION_ACTIVE_SESSION_UNSET
The action used to indicate that the active session has been set to null. This should be used as an action in an IntentFilter and BroadcastReceiver registered with the LocalBroadcastManager.

See Also:
Constant Field Values

ACTION_ACTIVE_SESSION_OPENED

public static final String ACTION_ACTIVE_SESSION_OPENED
The action used to indicate that the active session has been opened. This should be used as an action in an IntentFilter and BroadcastReceiver registered with the LocalBroadcastManager.

See Also:
Constant Field Values

ACTION_ACTIVE_SESSION_CLOSED

public static final String ACTION_ACTIVE_SESSION_CLOSED
The action used to indicate that the active session has been closed. This should be used as an action in an IntentFilter and BroadcastReceiver registered with the LocalBroadcastManager.

See Also:
Constant Field Values

APPLICATION_ID_PROPERTY

public static final String APPLICATION_ID_PROPERTY
Session takes application id as a constructor parameter. If this is null, Session will attempt to load the application id from application/meta-data using this String as the key.

See Also:
Constant Field Values
Constructor Detail

Session

public Session(Context currentContext)
Initializes a new Session with the specified context.

Parameters:
currentContext - The Activity or Service creating this Session.
Method Detail

getAuthorizationBundle

public final Bundle getAuthorizationBundle()
Returns a Bundle containing data that was returned from Facebook during authorization.

Returns:
a Bundle containing data that was returned from Facebook during authorization.

isOpened

public final boolean isOpened()
Returns a boolean indicating whether the session is opened.

Returns:
a boolean indicating whether the session is opened.

isClosed

public final boolean isClosed()

getState

public final SessionState getState()
Returns the current state of the Session. See SessionState for details.

Returns:
the current state of the Session.

getApplicationId

public final String getApplicationId()
Returns the application id associated with this Session.

Returns:
the application id associated with this Session.

getAccessToken

public final String getAccessToken()
Returns the access token String.

Returns:
the access token String, or null if there is no access token

getExpirationDate

public final Date getExpirationDate()

Returns the Date at which the current token will expire.

Note that Session automatically attempts to extend the lifetime of Tokens as needed when Facebook requests are made.

Returns:
the Date at which the current token will expire, or null if there is no access token

getPermissions

public final List<String> getPermissions()

Returns the list of permissions associated with the session.

If there is a valid token, this represents the permissions granted by that token. This can change during calls to requestNewReadPermissions(com.facebook.Session.NewPermissionsRequest) or requestNewPublishPermissions(com.facebook.Session.NewPermissionsRequest).

Returns:
the list of permissions associated with the session, or null if there is no access token

openForRead

public final void openForRead(Session.OpenRequest openRequest)

Logs a user in to Facebook.

A session may not be used with Request and other classes in the SDK until it is open. If, prior to calling open, the session is in the CREATED_TOKEN_LOADED state, and the requested permissions are a subset of the previously authorized permissions, then the Session becomes usable immediately with no user interaction.

The permissions associated with the openRequest passed to this method must be read permissions only (or null/empty). It is not allowed to pass publish permissions to this method and will result in an exception being thrown.

Any open method must be called at most once, and cannot be called after the Session is closed. Calling the method at an invalid time will result in UnsuportedOperationException.

Parameters:
openRequest - the open request, can be null only if the Session is in the CREATED_TOKEN_LOADED state
Throws:
FacebookException - if any publish or manage permissions are requested

openForPublish

public final void openForPublish(Session.OpenRequest openRequest)

Logs a user in to Facebook.

A session may not be used with Request and other classes in the SDK until it is open. If, prior to calling open, the session is in the CREATED_TOKEN_LOADED state, and the requested permissions are a subset of the previously authorized permissions, then the Session becomes usable immediately with no user interaction.

The permissions associated with the openRequest passed to this method must be publish or manage permissions only and must be non-empty. Any read permissions will result in a warning, and may fail during server-side authorization.

Any open method must be called at most once, and cannot be called after the Session is closed. Calling the method at an invalid time will result in UnsuportedOperationException.

Parameters:
openRequest - the open request, can be null only if the Session is in the CREATED_TOKEN_LOADED state
Throws:
FacebookException - if the passed in request is null or has no permissions set.

open

public final void open(AccessToken accessToken,
                       Session.StatusCallback callback)
Opens a session based on an existing Facebook access token. This method should be used only in instances where an application has previously obtained an access token and wishes to import it into the Session/TokenCachingStrategy-based session-management system. An example would be an application which previously did not use the Facebook SDK for Android and implemented its own session-management scheme, but wishes to implement an upgrade path for existing users so they do not need to log in again when upgrading to a version of the app that uses the SDK.

No validation is done that the token, token source, or permissions are actually valid. It is the caller's responsibility to ensure that these accurately reflect the state of the token that has been passed in, or calls to the Facebook API may fail.

Parameters:
accessToken - the access token obtained from Facebook
callback - a callback that will be called when the session status changes; may be null

requestNewReadPermissions

public final void requestNewReadPermissions(Session.NewPermissionsRequest newPermissionsRequest)

Issues a request to add new read permissions to the Session.

If successful, this will update the set of permissions on this session to match the newPermissions. If this fails, the Session remains unchanged.

The permissions associated with the newPermissionsRequest passed to this method must be read permissions only (or null/empty). It is not allowed to pass publish permissions to this method and will result in an exception being thrown.

Parameters:
newPermissionsRequest - the new permissions request

requestNewPublishPermissions

public final void requestNewPublishPermissions(Session.NewPermissionsRequest newPermissionsRequest)

Issues a request to add new publish or manage permissions to the Session.

If successful, this will update the set of permissions on this session to match the newPermissions. If this fails, the Session remains unchanged.

The permissions associated with the newPermissionsRequest passed to this method must be publish or manage permissions only and must be non-empty. Any read permissions will result in a warning, and may fail during server-side authorization.

Parameters:
newPermissionsRequest - the new permissions request

onActivityResult

public final boolean onActivityResult(Activity currentActivity,
                                      int requestCode,
                                      int resultCode,
                                      Intent data)
Provides an implementation for onActivityResult that updates the Session based on information returned during the authorization flow. The Activity that calls open or requestNewPermissions should forward the resulting onActivityResult call here to update the Session state based on the contents of the resultCode and data.

Parameters:
currentActivity - The Activity that is forwarding the onActivityResult call.
requestCode - The requestCode parameter from the forwarded call. When this onActivityResult occurs as part of Facebook authorization flow, this value is the activityCode passed to open or authorize.
resultCode - An int containing the resultCode parameter from the forwarded call.
data - The Intent passed as the data parameter from the forwarded call.
Returns:
A boolean indicating whether the requestCode matched a pending authorization request for this Session.

close

public final void close()
Closes the local in-memory Session object, but does not clear the persisted token cache.


closeAndClearTokenInformation

public final void closeAndClearTokenInformation()
Closes the local in-memory Session object and clears any persisted token cache related to the Session.


addCallback

public final void addCallback(Session.StatusCallback callback)
Adds a callback that will be called when the state of this Session changes.

Parameters:
callback - the callback

removeCallback

public final void removeCallback(Session.StatusCallback callback)
Removes a StatusCallback from this Session.

Parameters:
callback - the callback

toString

public String toString()
Overrides:
toString in class Object

saveSession

public static final void saveSession(Session session,
                                     Bundle bundle)
Save the Session object into the supplied Bundle.

Parameters:
session - the Session to save
bundle - the Bundle to save the Session to

restoreSession

public static final Session restoreSession(Context context,
                                           TokenCachingStrategy cachingStrategy,
                                           Session.StatusCallback callback,
                                           Bundle bundle)
Restores the saved session from a Bundle, if any. Returns the restored Session or null if it could not be restored.

Parameters:
context - the Activity or Service creating the Session, must not be null
cachingStrategy - the TokenCachingStrategy to use to load and store the token. If this is null, a default token cachingStrategy that stores data in SharedPreferences will be used
callback - the callback to notify for Session state changes, can be null
bundle - the bundle to restore the Session from
Returns:
the restored Session, or null

getActiveSession

public static final Session getActiveSession()
Returns the current active Session, or null if there is none.

Returns:
the current active Session, or null if there is none.

setActiveSession

public static final void setActiveSession(Session session)

Sets the current active Session.

The active Session is used implicitly by predefined Request factory methods as well as optionally by UI controls in the sdk.

It is legal to set this to null, or to a Session that is not yet open.

Parameters:
session - A Session to use as the active Session, or null to indicate that there is no active Session.

openActiveSessionFromCache

public static Session openActiveSessionFromCache(Context context)
Create a new Session, and if a token cache is available, open the Session and make it active without any user interaction.

Parameters:
context - The Context creating this session
Returns:
The new session or null if one could not be created

openActiveSession

public static Session openActiveSession(Activity activity,
                                        boolean allowLoginUI,
                                        Session.StatusCallback callback)
If allowLoginUI is true, this will create a new Session, make it active, and open it. If the default token cache is not available, then this will request basic permissions. If the default token cache is available and cached tokens are loaded, this will use the cached token and associated permissions.

If allowedLoginUI is false, this will only create the active session and open it if it requires no user interaction (i.e. the token cache is available and there are cached tokens).

Parameters:
activity - The Activity that is opening the new Session.
allowLoginUI - if false, only sets the active session and opens it if it does not require user interaction
callback - The SessionStatusCallback to notify regarding Session state changes. May be null.
Returns:
The new Session or null if one could not be created

openActiveSession

public static Session openActiveSession(Context context,
                                        Fragment fragment,
                                        boolean allowLoginUI,
                                        Session.StatusCallback callback)
If allowLoginUI is true, this will create a new Session, make it active, and open it. If the default token cache is not available, then this will request basic permissions. If the default token cache is available and cached tokens are loaded, this will use the cached token and associated permissions.

If allowedLoginUI is false, this will only create the active session and open it if it requires no user interaction (i.e. the token cache is available and there are cached tokens).

Parameters:
context - The Activity or Service creating this Session
fragment - The Fragment that is opening the new Session.
allowLoginUI - if false, only sets the active session and opens it if it does not require user interaction
callback - The SessionStatusCallback to notify regarding Session state changes.
Returns:
The new Session or null if one could not be created

openActiveSessionWithAccessToken

public static Session openActiveSessionWithAccessToken(Context context,
                                                       AccessToken accessToken,
                                                       Session.StatusCallback callback)
Opens a session based on an existing Facebook access token, and also makes this session the currently active session. This method should be used only in instances where an application has previously obtained an access token and wishes to import it into the Session/TokenCachingStrategy-based session-management system. A primary example would be an application which previously did not use the Facebook SDK for Android and implemented its own session-management scheme, but wishes to implement an upgrade path for existing users so they do not need to log in again when upgrading to a version of the app that uses the SDK. In general, this method will be called only once, when the app detects that it has been upgraded -- after that, the usual Session lifecycle methods should be used to manage the session and its associated token.

No validation is done that the token, token source, or permissions are actually valid. It is the caller's responsibility to ensure that these accurately reflect the state of the token that has been passed in, or calls to the Facebook API may fail.

Parameters:
context - the Context to use for creation the session
accessToken - the access token obtained from Facebook
callback - a callback that will be called when the session status changes; may be null
Returns:
The new Session or null if one could not be created

hashCode

public int hashCode()
Overrides:
hashCode in class Object

equals

public boolean equals(Object otherObj)
Overrides:
equals in class Object