com.dropbox.client2.session

Class WebAuthSession

java.lang.Object

com.dropbox.client2.session.AbstractSession

com.dropbox.client2.session.WebAuthSession

All Implemented Interfaces:

Session

public class WebAuthSession
extends AbstractSession

Keeps track of a logged in user contains configuration options for the DropboxAPI. This type of Session uses the web OAuth flow to authenticate users:

1. A request token + secret and redirect URL are retrieved using getAuthInfo() or getAuthInfo(String).
2. You store the request token + secret, and redirect the user to the redirect URL where they will authenticate with Dropbox and grant your app permission to access their account.
3. Dropbox will redirect back to your site if it was provided a URL to do so (otherwise, you have to ask the user when he/she is done).
4. The user's access token + secret are set on this session when you call retrieveWebAccessToken(RequestTokenPair) with the previously-saved request token + secret. You have a limited amount of time to make this call or the request token will expire.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	WebAuthSession.WebAuthInfo Contains the info needed to send the user to the Dropbox web auth page and later retrieve an access token + secret.

Nested classes/interfaces inherited from interface com.dropbox.client2.session.Session

Session.AccessType, Session.ProxyInfo

Constructor Summary

Constructors

Constructor and Description
WebAuthSession(AppKeyPair appKeyPair) Creates a new web auth session with the given app key pair.
WebAuthSession(AppKeyPair appKeyPair, AccessTokenPair accessTokenPair) Creates a new web auth session with the given app key pair.
WebAuthSession(AppKeyPair appKeyPair, Session.AccessType type) Deprecated. You don't need to specify the access type anymore. Use WebAuthSession(AppKeyPair).
WebAuthSession(AppKeyPair appKeyPair, Session.AccessType type, AccessTokenPair accessTokenPair) Deprecated. You don't need to specify the access type anymore. Use WebAuthSession(AppKeyPair, AccessTokenPair).

Method Summary

Methods

Modifier and Type	Method and Description
WebAuthSession.WebAuthInfo	getAuthInfo() Starts an authentication request with Dropbox servers and gets all the info you need to start authenticating a user.
WebAuthSession.WebAuthInfo	getAuthInfo(java.lang.String callbackUrl) Starts an authentication request with Dropbox servers and gets all the info you need to start authenticating a user.
java.lang.String	retrieveWebAccessToken(RequestTokenPair requestTokenPair) When called after the user is done authenticating, sets the user's access token + secret on this session.

Methods inherited from class com.dropbox.client2.session.AbstractSession

getAccessTokenPair, getAccessType, getAPIServer, getAppKeyPair, getContentServer, getHttpClient, getLocale, getOAuth2AccessToken, getProxyInfo, getWebServer, isLinked, setAccessTokenPair, setOAuth2AccessToken, setRequestTimeout, sign, unlink

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

WebAuthSession

public WebAuthSession(AppKeyPair appKeyPair,
              Session.AccessType type)

Deprecated. You don't need to specify the access type anymore. Use WebAuthSession(AppKeyPair).

Creates a new web auth session with the given app key pair and access type. The session will not be linked because it has no access token or secret.

WebAuthSession

public WebAuthSession(AppKeyPair appKeyPair,
              Session.AccessType type,
              AccessTokenPair accessTokenPair)

Deprecated. You don't need to specify the access type anymore. Use WebAuthSession(AppKeyPair, AccessTokenPair).

Creates a new web auth session with the given app key pair and access type. The session will be linked to the account corresponding to the given OAuth 1 access token pair.

WebAuthSession

public WebAuthSession(AppKeyPair appKeyPair)

Creates a new web auth session with the given app key pair. The session will not be linked because it has no access token or secret.

WebAuthSession

public WebAuthSession(AppKeyPair appKeyPair,
              AccessTokenPair accessTokenPair)

Creates a new web auth session with the given app key pair. The session will be linked to the account corresponding to the given access token pair.

Method Detail

getAuthInfo

public WebAuthSession.WebAuthInfo getAuthInfo()
                                       throws DropboxException

Starts an authentication request with Dropbox servers and gets all the info you need to start authenticating a user. This call blocks for a non-trivial amount of time due to a network operation. Because a callback URL is not provided, you will have to somehow determine when the user has finished authenticating on the Dropbox site (for example, put up a prompt after you open a browser window for authentication). If you want to provide a callback URL, see getAuthInfo(String).

Returns:

a WebAuthSession.WebAuthInfo, from which you can obtain the URL to redirect the user to and a request token + secret to log the user in later.

Throws:

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 500, 502, and 503 (all related to internal Dropbox server issues).

DropboxIOException - if any network-related error occurs.

DropboxParseException - if a malformed or unknown response was received from the server.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

getAuthInfo

public WebAuthSession.WebAuthInfo getAuthInfo(java.lang.String callbackUrl)
                                       throws DropboxException

Starts an authentication request with Dropbox servers and gets all the info you need to start authenticating a user. This call blocks for a non-trivial amount of time due to a network operation.

Parameters:

callbackUrl - the URL to which Dropbox will redirect the user after he/she has authenticated on the Dropbox site.

Returns:

a WebAuthSession.WebAuthInfo, from which you can obtain the URL to redirect the user to and a request token + secret to log the user in later.

Throws:

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 500, 502, and 503 (all for internal Dropbox server issues).

DropboxIOException - if any network-related error occurs.

DropboxParseException - if a malformed or unknown response was received from the server.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.

retrieveWebAccessToken

public java.lang.String retrieveWebAccessToken(RequestTokenPair requestTokenPair)
                                        throws DropboxException

When called after the user is done authenticating, sets the user's access token + secret on this session. This call blocks for a non-trivial amount of time due to a network operation. Since the request token + secret expire after a short time (currently 5 minutes), this should be called right after a user comes back from auth on the Dropbox site.

Parameters:

requestTokenPair - the request token pair from the WebAuthSession.WebAuthInfo returned from getAuthInfo().

Returns:

the Dropbox UID of the authenticated user.

Throws:

DropboxServerException - if the server responds with an error code. See the constants in DropboxServerException for the meaning of each error code. The most common error codes you can expect from this call are 401 (bad request token), 403 (bad app key pair), 500, 502, and 503 (all for internal Dropbox server issues).

DropboxIOException - if any network-related error occurs.

DropboxParseException - if a malformed or unknown response was received from the server.

DropboxException - for any other unknown errors. This is also a superclass of all other Dropbox exceptions, so you may want to only catch this exception which signals that some kind of error occurred.