com.dropbox.client2.session
Class WebAuthSession

java.lang.Object
  extended by com.dropbox.client2.session.AbstractSession
      extended by 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
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
WebAuthSession(AppKeyPair appKeyPair, Session.AccessType type)
          Creates a new web auth session with the given app key pair and access type.
WebAuthSession(AppKeyPair appKeyPair, Session.AccessType type, AccessTokenPair accessTokenPair)
          Creates a new web auth session with the given app key pair and access type.
 
Method Summary
 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, getProxyInfo, getWebServer, isLinked, setAccessTokenPair, 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)
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)
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 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.