com.box.sdk

Class BoxAPIConnection

Object

BoxAPIConnection

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, 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

Methods

Modifier and Type	Method and Description
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.
long	getExpires() Gets the amount of time for which this connection's access token is valid.
int	getMaxRequestAttempts() Gets the maximum number of times an API request will be tried when an error occurs.
String	getRefreshToken() Gets a refresh token that can be used to refresh an access token.
boolean	needsRefresh() Determines if this connection's access token has expired and needs to be refreshed.
void	refresh() Refresh's this connection's access token using its refresh token.
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	setMaxRequestAttempts(int attempts) Sets the maximum number of times an API request will be tried when an error occurs.
void	setRefreshToken(String refreshToken) Sets the refresh token to use when refreshing an access token.

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.

Method Detail

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.

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.

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.

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.

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.

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.