com.box.sdk

Class BoxAPIConnection

Object

BoxAPIConnection

Direct Known Subclasses:

BoxDeveloperEditionAPIConnection

public class BoxAPIConnection
extends Object

Represents an authenticated connection to the Box API.

This class handles storing authentication information, automatic token refresh, and rate-limiting. It can also be used to configure the Box API endpoint URL in order to hit a different version of the API. Multiple instances of BoxAPIConnection may be created to support multi-user login.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_MAX_ATTEMPTS The default maximum number of times an API request will be tried when an error occurs.

Constructor Summary

Constructors

Constructor and Description
BoxAPIConnection(String accessToken) Constructs a new BoxAPIConnection that authenticates with a developer or access token.
BoxAPIConnection(String clientID, String clientSecret) Constructs a new BoxAPIConnection.
BoxAPIConnection(String clientID, String clientSecret, String authCode) Constructs a new BoxAPIConnection with an auth code that was obtained from the first half of OAuth.
BoxAPIConnection(String clientID, String clientSecret, String accessToken, String refreshToken) Constructs a new BoxAPIConnection with an access token that can be refreshed.

Method Summary

Modifier and Type	Method and Description
void	addListener(BoxAPIConnectionListener listener) Add a listener to listen to Box API connection events.
void	authenticate(String authCode) Authenticates the API connection by obtaining access and refresh tokens using the auth code that was obtained from the first half of OAuth.
boolean	canRefresh() Determines if this connection's access token can be refreshed.
String	getAccessToken() Gets an access token that can be used to authenticate an API request.
boolean	getAutoRefresh() Gets whether or not automatic refreshing of this connection's access token is enabled.
String	getBaseUploadURL() Gets the base upload URL that's used when performing file uploads to Box.
String	getBaseURL() Gets the base URL that's used when sending requests to the Box API.
String	getClientID() Gets the client ID.
String	getClientSecret() Gets the client secret.
long	getExpires() Gets the amount of time for which this connection's access token is valid.
long	getLastRefresh() Gets the last time that the access token was refreshed.
int	getMaxRequestAttempts() Gets the maximum number of times an API request will be tried when an error occurs.
Proxy	getProxy() Gets the proxy value to use for API calls to Box.
String	getProxyPassword() Gets the password to use for a proxy that requires basic auth.
String	getProxyUsername() Gets the username to use for a proxy that requires basic auth.
protected ReadWriteLock	getRefreshLock() Gets the refresh lock to be used when refreshing an access token.
String	getRefreshToken() Gets a refresh token that can be used to refresh an access token.
RequestInterceptor	getRequestInterceptor() Gets the RequestInterceptor associated with this API connection.
String	getTokenURL() Gets the token URL that's used to request access tokens.
String	getUserAgent() Gets the user agent that's used when sending requests to the Box API.
boolean	needsRefresh() Determines if this connection's access token has expired and needs to be refreshed.
protected void	notifyError(BoxAPIException error) Notifies an error event to all the listeners.
protected void	notifyRefresh() Notifies a refresh event to all the listeners.
void	refresh() Refresh's this connection's access token using its refresh token.
void	removeListener(BoxAPIConnectionListener listener) Remove a listener listening to Box API connection events.
void	restore(String state) Restores a saved connection state into this BoxAPIConnection.
static BoxAPIConnection	restore(String clientID, String clientSecret, String state) Restores a BoxAPIConnection from a saved state.
String	save() Saves the state of this connection to a string so that it can be persisted and restored at a later time.
void	setAccessToken(String accessToken) Sets the access token to use when authenticating API requests.
void	setAutoRefresh(boolean autoRefresh) Enables or disables automatic refreshing of this connection's access token.
void	setBaseUploadURL(String baseUploadURL) Sets the base upload URL to be used when performing file uploads to Box.
void	setBaseURL(String baseURL) Sets the base URL to be used when sending requests to the Box API.
void	setExpires(long milliseconds) Sets the amount of time for which this connection's access token is valid before it must be refreshed.
void	setLastRefresh(long lastRefresh) Sets the last time that the access token was refreshed.
void	setMaxRequestAttempts(int attempts) Sets the maximum number of times an API request will be tried when an error occurs.
void	setProxy(Proxy proxy) Sets the proxy to use for API calls to Box.
void	setProxyPassword(String proxyPassword) Sets the password to use for a proxy that requires basic auth.
void	setProxyUsername(String proxyUsername) Sets the username to use for a proxy that requires basic auth.
void	setRefreshToken(String refreshToken) Sets the refresh token to use when refreshing an access token.
void	setRequestInterceptor(RequestInterceptor interceptor) Sets a RequestInterceptor that can intercept requests and manipulate them before they're sent to the Box API.
void	setTokenURL(String tokenURL) Sets the token URL that's used to request access tokens.
void	setUserAgent(String userAgent) Sets the user agent to be used when sending requests to the Box API.

Methods inherited from class Object

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

Field Detail

DEFAULT_MAX_ATTEMPTS

public static final int DEFAULT_MAX_ATTEMPTS

The default maximum number of times an API request will be tried when an error occurs.

See Also:

Constant Field Values

Constructor Detail

BoxAPIConnection

public BoxAPIConnection(String accessToken)

Constructs a new BoxAPIConnection that authenticates with a developer or access token.

Parameters:

accessToken - a developer or access token to use for authenticating with the API.

BoxAPIConnection

public BoxAPIConnection(String clientID,
                        String clientSecret,
                        String accessToken,
                        String refreshToken)

Constructs a new BoxAPIConnection with an access token that can be refreshed.

Parameters:

clientID - the client ID to use when refreshing the access token.

clientSecret - the client secret to use when refreshing the access token.

accessToken - an initial access token to use for authenticating with the API.

refreshToken - an initial refresh token to use when refreshing the access token.

BoxAPIConnection

public BoxAPIConnection(String clientID,
                        String clientSecret,
                        String authCode)

Constructs a new BoxAPIConnection with an auth code that was obtained from the first half of OAuth.

Parameters:

clientID - the client ID to use when exchanging the auth code for an access token.

clientSecret - the client secret to use when exchanging the auth code for an access token.

authCode - an auth code obtained from the first half of the OAuth process.

BoxAPIConnection

public BoxAPIConnection(String clientID,
                        String clientSecret)

Constructs a new BoxAPIConnection.

Parameters:

clientID - the client ID to use when exchanging the auth code for an access token.

clientSecret - the client secret to use when exchanging the auth code for an access token.

Method Detail

restore

public static BoxAPIConnection restore(String clientID,
                                       String clientSecret,
                                       String state)

Restores a BoxAPIConnection from a saved state.

Parameters:

clientID - the client ID to use with the connection.

clientSecret - the client secret to use with the connection.

state - the saved state that was created with save().

Returns:

a restored API connection.

See Also:

save()

authenticate

public void authenticate(String authCode)

Authenticates the API connection by obtaining access and refresh tokens using the auth code that was obtained from the first half of OAuth.

Parameters:

authCode - the auth code obtained from the first half of the OAuth process.

getClientID

public String getClientID()

Gets the client ID.

Returns:

the client ID.

getClientSecret

public String getClientSecret()

Gets the client secret.

Returns:

the client secret.

setExpires

public void setExpires(long milliseconds)

Sets the amount of time for which this connection's access token is valid before it must be refreshed.

Parameters:

milliseconds - the number of milliseconds for which the access token is valid.

getExpires

public long getExpires()

Gets the amount of time for which this connection's access token is valid.

Returns:

the amount of time in milliseconds.

getTokenURL

public String getTokenURL()

Gets the token URL that's used to request access tokens. The default value is "https://www.box.com/api/oauth2/token".

Returns:

the token URL.

setTokenURL

public void setTokenURL(String tokenURL)

Sets the token URL that's used to request access tokens. For example, the default token URL is "https://www.box.com/api/oauth2/token".

Parameters:

tokenURL - the token URL.

getBaseURL

public String getBaseURL()

Gets the base URL that's used when sending requests to the Box API. The default value is "https://api.box.com/2.0/".

Returns:

the base URL.

setBaseURL

public void setBaseURL(String baseURL)

Sets the base URL to be used when sending requests to the Box API. For example, the default base URL is "https://api.box.com/2.0/".

Parameters:

baseURL - a base URL

getBaseUploadURL

public String getBaseUploadURL()

Gets the base upload URL that's used when performing file uploads to Box.

Returns:

the base upload URL.

setBaseUploadURL

public void setBaseUploadURL(String baseUploadURL)

Sets the base upload URL to be used when performing file uploads to Box.

Parameters:

baseUploadURL - a base upload URL.

getUserAgent

public String getUserAgent()

Gets the user agent that's used when sending requests to the Box API.

Returns:

the user agent.

setUserAgent

public void setUserAgent(String userAgent)

Sets the user agent to be used when sending requests to the Box API.

Parameters:

userAgent - the user agent.

getAccessToken

public String getAccessToken()

Gets an access token that can be used to authenticate an API request. This method will automatically refresh the access token if it has expired since the last call to getAccessToken().

Returns:

a valid access token that can be used to authenticate an API request.

setAccessToken

public void setAccessToken(String accessToken)

Sets the access token to use when authenticating API requests.

Parameters:

accessToken - a valid access token to use when authenticating API requests.

getRefreshLock

protected ReadWriteLock getRefreshLock()

Gets the refresh lock to be used when refreshing an access token.

Returns:

the refresh lock.

getRefreshToken

public String getRefreshToken()

Gets a refresh token that can be used to refresh an access token.

Returns:

a valid refresh token.

setRefreshToken

public void setRefreshToken(String refreshToken)

Sets the refresh token to use when refreshing an access token.

Parameters:

refreshToken - a valid refresh token.

getLastRefresh

public long getLastRefresh()

Gets the last time that the access token was refreshed.

Returns:

the last refresh time in milliseconds.

setLastRefresh

public void setLastRefresh(long lastRefresh)

Sets the last time that the access token was refreshed.

This value is used when determining if an access token needs to be auto-refreshed. If the amount of time since the last refresh exceeds the access token's expiration time, then the access token will be refreshed.

Parameters:

lastRefresh - the new last refresh time in milliseconds.

setAutoRefresh

public void setAutoRefresh(boolean autoRefresh)

Enables or disables automatic refreshing of this connection's access token. Defaults to true.

Parameters:

autoRefresh - true to enable auto token refresh; otherwise false.

getAutoRefresh

public boolean getAutoRefresh()

Gets whether or not automatic refreshing of this connection's access token is enabled. Defaults to true.

Returns:

true if auto token refresh is enabled; otherwise false.

getMaxRequestAttempts

public int getMaxRequestAttempts()

Gets the maximum number of times an API request will be tried when an error occurs.

Returns:

the maximum number of request attempts.

setMaxRequestAttempts

public void setMaxRequestAttempts(int attempts)

Sets the maximum number of times an API request will be tried when an error occurs.

Parameters:

attempts - the maximum number of request attempts.

getProxy

public Proxy getProxy()

Gets the proxy value to use for API calls to Box.

Returns:

the current proxy.

setProxy

public void setProxy(Proxy proxy)

Sets the proxy to use for API calls to Box.

Parameters:

proxy - the proxy to use for API calls to Box.

getProxyUsername

public String getProxyUsername()

Gets the username to use for a proxy that requires basic auth.

Returns:

the username to use for a proxy that requires basic auth.

setProxyUsername

public void setProxyUsername(String proxyUsername)

Sets the username to use for a proxy that requires basic auth.

Parameters:

proxyUsername - the username to use for a proxy that requires basic auth.

getProxyPassword

public String getProxyPassword()

Gets the password to use for a proxy that requires basic auth.

Returns:

the password to use for a proxy that requires basic auth.

setProxyPassword

public void setProxyPassword(String proxyPassword)

Sets the password to use for a proxy that requires basic auth.

Parameters:

proxyPassword - the password to use for a proxy that requires basic auth.

canRefresh

public boolean canRefresh()

Determines if this connection's access token can be refreshed. An access token cannot be refreshed if a refresh token was never set.

Returns:

true if the access token can be refreshed; otherwise false.

needsRefresh

public boolean needsRefresh()

Determines if this connection's access token has expired and needs to be refreshed.

Returns:

true if the access token needs to be refreshed; otherwise false.

refresh

public void refresh()

Refresh's this connection's access token using its refresh token.

Throws:

IllegalStateException - if this connection's access token cannot be refreshed.

restore

public void restore(String state)

Restores a saved connection state into this BoxAPIConnection.

Parameters:

state - the saved state that was created with save().

See Also:

save()

notifyRefresh

protected void notifyRefresh()

Notifies a refresh event to all the listeners.

notifyError

protected void notifyError(BoxAPIException error)

Notifies an error event to all the listeners.

Parameters:

error - A BoxAPIException instance.

addListener

public void addListener(BoxAPIConnectionListener listener)

Add a listener to listen to Box API connection events.

Parameters:

listener - a listener to listen to Box API connection.

removeListener

public void removeListener(BoxAPIConnectionListener listener)

Remove a listener listening to Box API connection events.

Parameters:

listener - the listener to remove.

getRequestInterceptor

public RequestInterceptor getRequestInterceptor()

Gets the RequestInterceptor associated with this API connection.

Returns:

the RequestInterceptor associated with this API connection.

setRequestInterceptor

public void setRequestInterceptor(RequestInterceptor interceptor)

Sets a RequestInterceptor that can intercept requests and manipulate them before they're sent to the Box API.

Parameters:

interceptor - the RequestInterceptor.

save

public String save()

Saves the state of this connection to a string so that it can be persisted and restored at a later time.

Note that proxy settings aren't automatically saved or restored. This is mainly due to security concerns around persisting proxy authentication details to the state string. If your connection uses a proxy, you will have to manually configure it again after restoring the connection.

Returns:

the state of this connection.

See Also:

restore(java.lang.String, java.lang.String, java.lang.String)