BoxAPIConnection (Box Java SDK)

Object
- BoxAPIConnection

Direct Known Subclasses:

BoxDeveloperEditionAPIConnection, BoxTransactionalAPIConnection, SharedLinkAPIConnection
```
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.

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(BoxConfig boxConfig)` Constructs a new BoxAPIConnection levaraging BoxConfig.
`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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addListener(BoxAPIConnectionListener listener)` Add a listener to listen to Box API connection events.
`void`	`asSelf()` Sets this API connection to make API calls on behalf of the user with whom the access token is associated.
`void`	`asUser(String userID)` Set this API connection to make API calls on behalf of another users, impersonating them.
`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.
`void`	`enableNotifications()` Re-enable email notifications from API actions if they have been suppressed.
`String`	`getAccessToken()` Gets an access token that can be used to authenticate an API request.
`static URL`	`getAuthorizationURL(String clientID, URI redirectUri, String state, List<String> scopes)` Return the authorization URL which is used to perform the authorization_code based OAuth2 flow.
`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.
`int`	`getConnectTimeout()` Gets the connect timeout for this connection in milliseconds.
`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.
`ScopedToken`	`getLowerScopedToken(List<String> scopes, String resource)` Get a lower-scoped token restricted to a resource for the list of scopes that are passed.
`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.
`int`	`getReadTimeout()` Gets the read timeout for this connection in milliseconds.
`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`	`getRevokeURL()` Returns the URL used for token revocation.
`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`	`removeCustomHeader(String header)` Removes a custom header, so it will no longer be sent on requests through this API connection.
`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.
`void`	`revokeToken()` Revokes the tokens associated with this API connection.
`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`	`setConnectTimeout(int connectTimeout)` Sets the connect timeout for this connection.
`void`	`setCustomHeader(String header, String value)` Sets a custom header to be sent on all requests through this API connection.
`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`	`setReadTimeout(int readTimeout)` Sets the read timeout for this connection.
`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`	`setRevokeURL(String url)` Set the URL used for token revocation.
`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.
`void`	`suppressNotifications()` Suppresses email notifications from API actions.

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.
  - BoxAPIConnection
```
public BoxAPIConnection(BoxConfig boxConfig)
```
    Constructs a new BoxAPIConnection levaraging BoxConfig.
    
    Parameters:
    
    boxConfig - BoxConfig file, which should have clientId and clientSecret
- 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()
  - getAuthorizationURL
```
public static URL getAuthorizationURL(String clientID,
                                      URI redirectUri,
                                      String state,
                                      List<String> scopes)
```
    Return the authorization URL which is used to perform the authorization_code based OAuth2 flow.
    
    Parameters:
    
    clientID - the client ID to use with the connection.
    
    redirectUri - the URL to which Box redirects the browser when authentication completes.
    
    state - the text string that you choose. Box sends the same string to your redirect URL when authentication is complete.
    
    scopes - this optional parameter identifies the Box scopes available to the application once it's authenticated.
    
    Returns:
    
    the authorization URL
  - 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.
  - setRevokeURL
```
public void setRevokeURL(String url)
```
    Set the URL used for token revocation.
    
    Parameters:
    
    url - The url to use.
  - getRevokeURL
```
public String getRevokeURL()
```
    Returns the URL used for token revocation.
    
    Returns:
    
    The url used for token revocation.
  - 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.
  - getConnectTimeout
```
public int getConnectTimeout()
```
    Gets the connect timeout for this connection in milliseconds.
    
    Returns:
    
    the number of milliseconds to connect before timing out.
  - setConnectTimeout
```
public void setConnectTimeout(int connectTimeout)
```
    Sets the connect timeout for this connection.
    
    Parameters:
    
    connectTimeout - The number of milliseconds to wait for the connection to be established.
  - getReadTimeout
```
public int getReadTimeout()
```
    Gets the read timeout for this connection in milliseconds.
    
    Returns:
    
    the number of milliseconds to wait for bytes to be read before timing out.
  - setReadTimeout
```
public void setReadTimeout(int readTimeout)
```
    Sets the read timeout for this connection.
    
    Parameters:
    
    readTimeout - The number of milliseconds to wait for bytes to be read.
  - 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.
  - getLowerScopedToken
```
public ScopedToken getLowerScopedToken(List<String> scopes,
                                       String resource)
```
    Get a lower-scoped token restricted to a resource for the list of scopes that are passed.
    
    Parameters:
    
    scopes - the list of scopes to which the new token should be restricted for
    
    resource - the resource for which the new token has to be obtained
    
    Returns:
    
    scopedToken which has access token and other details
  - revokeToken
```
public void revokeToken()
```
    Revokes the tokens associated with this API connection. This results in the connection no longer being able to make API calls until a fresh authorization is made by calling authenticate()
  - 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)
  - setCustomHeader
```
public void setCustomHeader(String header,
                            String value)
```
    Sets a custom header to be sent on all requests through this API connection.
    
    Parameters:
    
    header - the header name.
    
    value - the header value.
  - removeCustomHeader
```
public void removeCustomHeader(String header)
```
    Removes a custom header, so it will no longer be sent on requests through this API connection.
    
    Parameters:
    
    header - the header name.
  - suppressNotifications
```
public void suppressNotifications()
```
    Suppresses email notifications from API actions. This is typically used by security or admin applications to prevent spamming end users when doing automated processing on their content.
  - enableNotifications
```
public void enableNotifications()
```
    Re-enable email notifications from API actions if they have been suppressed.
    
    See Also:
    
    suppressNotifications()
  - asUser
```
public void asUser(String userID)
```
    Set this API connection to make API calls on behalf of another users, impersonating them. This functionality can only be used by admins and service accounts.
    
    Parameters:
    
    userID - the ID of the user to act as.
  - asSelf
```
public void asSelf()
```
    Sets this API connection to make API calls on behalf of the user with whom the access token is associated. This undoes any previous calls to asUser().
    
    See Also:
    
    asUser(java.lang.String)

Class BoxAPIConnection

Field Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Field Detail

DEFAULT_MAX_ATTEMPTS

Constructor Detail

BoxAPIConnection

BoxAPIConnection

BoxAPIConnection

BoxAPIConnection

BoxAPIConnection

Method Detail

restore

getAuthorizationURL

authenticate

getClientID

getClientSecret

setExpires

getExpires

getTokenURL

setTokenURL

setRevokeURL

getRevokeURL

getBaseURL

setBaseURL

getBaseUploadURL

setBaseUploadURL

getUserAgent

setUserAgent

getAccessToken

setAccessToken

getRefreshLock

getRefreshToken

setRefreshToken

getLastRefresh

setLastRefresh

setAutoRefresh

getAutoRefresh

getMaxRequestAttempts

setMaxRequestAttempts

getConnectTimeout

setConnectTimeout

getReadTimeout

setReadTimeout

getProxy

setProxy

getProxyUsername

setProxyUsername

getProxyPassword

setProxyPassword

canRefresh

needsRefresh

refresh

restore

notifyRefresh

notifyError

addListener

removeListener

getRequestInterceptor

setRequestInterceptor

getLowerScopedToken

revokeToken

save

setCustomHeader

removeCustomHeader

suppressNotifications

enableNotifications

asUser

asSelf