com.box.boxjavalibv2

Class BoxClient

java.lang.Object

com.box.boxjavalibv2.dao.BoxBase

com.box.boxjavalibv2.BoxClient

All Implemented Interfaces:

IAuthFlowListener

public class BoxClient
extends BoxBase
implements IAuthFlowListener

This is the main entrance of the sdk. The client contains all resource managers and also handles authentication. Make sure you call authenticate method before making any api calls. you can use the resource managers to execute requests synchronously against the Box REST API(V2). Full details about the Box API can be found at @see http://developers.box.com/docs. You must have an OpenBox application with a valid API key to use the Box API. All methods in this class are executed in the invoking thread, and therefore are NOT safe to execute in the UI thread of your application. You should only use this class if you already have worker threads or AsyncTasks that you want to incorporate the Box API into.

Constructor Summary

Constructors

Constructor and Description
BoxClient(java.lang.String clientId, java.lang.String clientSecret, IBoxConfig config) Deprecated.
BoxClient(java.lang.String clientId, java.lang.String clientSecret, IBoxResourceHub hub, IBoxJSONParser parser, IBoxConfig config)
BoxClient(java.lang.String clientId, java.lang.String clientSecret, IBoxResourceHub hub, IBoxJSONParser parser, IBoxConfig config, BoxConnectionManagerBuilder.BoxConnectionManager connectionManager) This constructor has some connection parameters.
BoxClient(java.lang.String clientId, java.lang.String clientSecret, IBoxResourceHub hub, IBoxJSONParser parser, IBoxRESTClient restClient, IBoxConfig config)

Method Summary

Methods

Modifier and Type	Method and Description
void	addOAuthRefreshListener(OAuthRefreshListener listener) Add a listener to listen to OAuth refresh events.
void	authenticate(IAuthData authData) Get authenticated using a Auth object, this could be a previously stored data.
void	authenticate(IAuthFlowUI authFlowUI, boolean autoRefreshOAuth, IAuthFlowListener listener) Get authenticated.
void	authenticateFromSecureStorage(IAuthSecureStorage storage) Authenticate from the auth object stored in the secure storage.
void	clearBoxClientAuthListener() Clear the auth listener so it's not held by BoxClient any more.
protected IAuthDataController	createAuthDataController(java.lang.String clientId, java.lang.String clientSecret) Create auth data controller, which maintains auth data and handles auth refresh.
protected IBoxRequestAuth	createAuthorization(IAuthDataController controller) From auth data controller, generate IBoxRequestAuth, which can be applied to api requests.
protected IBoxJSONParser	createJSONParser(IBoxResourceHub resourceHub) Create a json parser.
protected static IBoxRESTClient	createMonitoredRestClient(BoxConnectionManagerBuilder.BoxConnectionManager connectionManager)
protected IBoxResourceHub	createResourceHub() Create a resource hub
protected static IBoxRESTClient	createRestClient() Create a REST client to make api calls.
IBoxRequestAuth	getAuth() Get the auth object used to make api calls.
IAuthData	getAuthData() Get available OAuthData.
OAuthDataController.OAuthTokenState	getAuthState() Check authentication state.
protected IAuthFlowListener	getBoxClientAuthenticationListener()
IBoxItemsManager	getBoxItemsManager() Get the BoxItemsManager, which can be used to make API calls on files/folders endpoints.
IBoxCollaborationsManager	getCollaborationsManager()
IBoxCollectionsManager	getCollectionsManager()
IBoxCommentsManager	getCommentsManager()
IBoxConfig	getConfig() Get config.
IBoxEventsManager	getEventsManager()
IBoxFilesManager	getFilesManager() Get the BoxFilesManager, which can be used to make API calls on files endpoints.
IBoxFoldersManager	getFoldersManager()
IBoxGroupsManager	getGroupsManager() Get the BoxGroupsManager, which can be used to make API calls on groups endpoints.
IBoxJSONParser	getJSONParser()
OAuthDataController	getOAuthDataController() Get the OAuthDataController that controls OAuth data.
IBoxOAuthManager	getOAuthManager() Get the OAuthManager, which can be used to make OAuth related api calls.
protected BoxOAuthToken	getOAuthTokenFromMessage(IAuthFlowMessage message)
IBoxResourceManager	getPluginManager(java.lang.String pluginManagerKey) Get a resource manager plugged in based on the key.
IBoxResourceHub	getResourceHub() Get resource hub.
IBoxResourceManager	getResourceManagerWithSharedLinkAuth(BoxResourceType type, java.lang.String sharedLink, java.lang.String password) A generic way to get a resourceManager with shared link auth.
protected IBoxRESTClient	getRestClient() Get rest client.
IBoxSearchManager	getSearchManager()
IBoxItemsManager	getSharedBoxItemsManager(java.lang.String sharedLink, java.lang.String password) Get the BoxItemsManager for items(files/folders) shared to you, this can be used to make API calls on files/folders endpoints.
IBoxCommentsManager	getSharedCommentsManager(java.lang.String sharedLink, java.lang.String password) Get the BoxCommentsManager for shared items, which can be used to make API calls on comments endpoints for a shared item.
IBoxFilesManager	getSharedFilesManager(java.lang.String sharedLink, java.lang.String password) Get the BoxFilesManager for shared items, which can be used to make API calls on files endpoints for a shared item.
IBoxFoldersManager	getSharedFoldersManager(java.lang.String sharedLink, java.lang.String password) Get the BoxFoldersManager for shared items, which can be used to make API calls on folders endpoints for a shared item.
IBoxRequestAuth	getSharedItemAuth(java.lang.String sharedLink, java.lang.String password) Get the authorization needed for shared items.
IBoxSharedItemsManager	getSharedItemsManager(java.lang.String sharedLink, java.lang.String password) Get Shared Items manager, which can be used to make API calls on shared item endpoints.
IBoxTrashManager	getTrashManager() Get the BoxItemsManager, which can be used to make API calls on files/folders endpoints for trashed files/folders.
IBoxUsersManager	getUsersManager()
IBoxWebLinksManager	getWebLinksManager()
IAuthData	guaranteedGetAuthData() Get OAuthData, in case of OAuthTokenState indicating refresh needed, do refresh.
boolean	isAuthenticated() Whether this client is authenticated.
void	onAuthFlowEvent(IAuthEvent event, IAuthFlowMessage message) On an event.
void	onAuthFlowException(java.lang.Exception e) On an exception.
void	onAuthFlowMessage(IAuthFlowMessage message) On a message.
IBoxResourceManager	pluginResourceManager(java.lang.String key, IPluginResourceManagerBuilder builder) Plug in a resource manager into sdk client.
void	saveAuth(IAuthSecureStorage storage) Save auth in a customized secure storage.
void	setAutoRefreshOAuth(boolean autoRefresh) Makes OAuth auto refresh itself when token expires.
protected void	setBoxClientAuthListener(IAuthFlowListener listener) set listener listening to the events of the states that this BoxClient gets authenticateds.
void	setConnectionOpen(boolean connectionOpen) Set whether we want the connection to keep open (and reused) after an api call.
void	setConnectionTimeOut(int timeOut) Set connection time out.

Methods inherited from class java.lang.Object

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

Constructor Detail

BoxClient

public BoxClient(java.lang.String clientId,
         java.lang.String clientSecret,
         IBoxResourceHub hub,
         IBoxJSONParser parser,
         IBoxConfig config,
         BoxConnectionManagerBuilder.BoxConnectionManager connectionManager)

This constructor has some connection parameters. They are used to periodically close idle connections that HttpClient opens.

Parameters:

clientId - client id, you can get it from dev console.

clientSecret - client secret, you can get it from dev console.

hub - resource hub. use null if you want to use default one.

parser - json parser, use null if you want to use default one(Jackson).

config - BoxConfig. User BoxConfigBuilder to build. Normally you only need default config: (new BoxConfigBuilder()).build()

connectionManager - BoxConnectionManager. Normally you only need default connection manager: (new BoxConnectionManagerBuilder()).build()

BoxClient

public BoxClient(java.lang.String clientId,
         java.lang.String clientSecret,
         IBoxResourceHub hub,
         IBoxJSONParser parser,
         IBoxConfig config)

Parameters:

clientId - client id

clientSecret - client secret

hub - resource hub, use null for default resource hub.

parser - json parser, use null for default parser.

config - BoxConfig. User BoxConfigBuilder to build. Normally you only need default config: (new BoxConfigBuilder()).build()

BoxClient

public BoxClient(java.lang.String clientId,
         java.lang.String clientSecret,
         IBoxResourceHub hub,
         IBoxJSONParser parser,
         IBoxRESTClient restClient,
         IBoxConfig config)

Parameters:

clientId - client id

clientSecret - client secret

hub - resource hub, use null for default resource hub.

parser - json parser, use null for default parser.

restClient - rest client

config - BoxConfig. User BoxConfigBuilder to build. Normally you only need default config: (new BoxConfigBuilder()).build()

BoxClient

@Deprecated
public BoxClient(java.lang.String clientId,
                    java.lang.String clientSecret,
                    IBoxConfig config)

Deprecated.

Method Detail

pluginResourceManager

public IBoxResourceManager pluginResourceManager(java.lang.String key,
                                        IPluginResourceManagerBuilder builder)

Plug in a resource manager into sdk client. The plugged in resource manager can be retrieved by getPluginManager(key).

Parameters:

key - key of the resource manager. The key is used to retrieve the plugged in resource manager.

builder - builder of the resource manager, the builder interface confines the base building blocks of the plugged in resource manager.

Returns:

The plugged in resource manager.

isAuthenticated

public boolean isAuthenticated()

Whether this client is authenticated.

Returns:

setAutoRefreshOAuth

public void setAutoRefreshOAuth(boolean autoRefresh)

Makes OAuth auto refresh itself when token expires. By default, this is set to true. Note if autorefresh fails, it's not going to try refresh again.

Parameters:

autoRefresh -

setConnectionOpen

public void setConnectionOpen(boolean connectionOpen)

Set whether we want the connection to keep open (and reused) after an api call.

Parameters:

connectionOpen - true if we want the connection to remain open and reused for another api call.

setConnectionTimeOut

public void setConnectionTimeOut(int timeOut)

Set connection time out.

Parameters:

timeOut -

getOAuthDataController

public OAuthDataController getOAuthDataController()

Get the OAuthDataController that controls OAuth data.

addOAuthRefreshListener

public void addOAuthRefreshListener(OAuthRefreshListener listener)

Add a listener to listen to OAuth refresh events. This is important because every time OAuth token refreshes, a new refresh/access token pair will be generated. If your app is storing the token pairs, it needs to get rid of the stale pair store the updated pair.

Parameters:

listener -

getAuthData

public IAuthData getAuthData()
                      throws AuthFatalFailureException

Get available OAuthData. Note depending on the OAuth token state, there is no guarantee that the OAuthData is valid. an example is that the token state is FAIL, which indicates the token is bad. In case you definitely want a valid token, use guaranteedGetAuthData() method instead.

Returns:

OAuthData

Throws:

AuthFatalFailureException

guaranteedGetAuthData

public IAuthData guaranteedGetAuthData()
                                throws AuthFatalFailureException

Get OAuthData, in case of OAuthTokenState indicating refresh needed, do refresh. Note this method may involve network operation so do not call on UI thread. In case you can tolerate invalid token and definitely don't want network calls involved, use getAuthData() method instead.

Throws:

AuthFatalFailureException

saveAuth

public void saveAuth(IAuthSecureStorage storage)
              throws AuthFatalFailureException

Save auth in a customized secure storage.

Parameters:

storage -

Throws:

AuthFatalFailureException

authenticateFromSecureStorage

public void authenticateFromSecureStorage(IAuthSecureStorage storage)

Authenticate from the auth object stored in the secure storage.

Parameters:

storage -

getFilesManager

public IBoxFilesManager getFilesManager()

Get the BoxFilesManager, which can be used to make API calls on files endpoints. Note this files manager only work on the folders you own. if you are trying to make api calls on a shared file (file shared to you via shared link), please use getSharedFilesManager().

Returns:

the filesManager

getBoxItemsManager

public IBoxItemsManager getBoxItemsManager()

Get the BoxItemsManager, which can be used to make API calls on files/folders endpoints. Note this files manager only work on the files/folders you own. if you are trying to make api calls on a shared file (file shared to you via shared link), please use getSharedBoxItemsManager(). In general this is a convenient resource manager when you make api calls for a BoxItem without knowing whether it's a BoxFile or BoxFolder.

Returns:

the boxItemsManager

getSharedBoxItemsManager

public IBoxItemsManager getSharedBoxItemsManager(java.lang.String sharedLink,
                                        java.lang.String password)

Get the BoxItemsManager for items(files/folders) shared to you, this can be used to make API calls on files/folders endpoints. Note this is different from getSharedItemsManager(), getSharedItemsManager is used for api calls on sharedItems endpoints.

Parameters:

sharedLink - shared link

password - use null if no password required.

Returns:

getTrashManager

public IBoxTrashManager getTrashManager()

Get the BoxItemsManager, which can be used to make API calls on files/folders endpoints for trashed files/folders.

Returns:

the boxItemsManager

getOAuthManager

public IBoxOAuthManager getOAuthManager()

Get the OAuthManager, which can be used to make OAuth related api calls.

Returns:

getGroupsManager

public IBoxGroupsManager getGroupsManager()

Get the BoxGroupsManager, which can be used to make API calls on groups endpoints.

getSharedItemsManager

public IBoxSharedItemsManager getSharedItemsManager(java.lang.String sharedLink,
                                           java.lang.String password)

Get Shared Items manager, which can be used to make API calls on shared item endpoints.

Parameters:

sharedLink - shared link

password - password

Returns:

BoxSharedItemsManager

getSharedFilesManager

public IBoxFilesManager getSharedFilesManager(java.lang.String sharedLink,
                                     java.lang.String password)

Get the BoxFilesManager for shared items, which can be used to make API calls on files endpoints for a shared item.

Parameters:

sharedLink - shared link.

password - password of the shared link, use null if there is no password

Returns:

BoxFilesManager

getSharedFoldersManager

public IBoxFoldersManager getSharedFoldersManager(java.lang.String sharedLink,
                                         java.lang.String password)

Get the BoxFoldersManager for shared items, which can be used to make API calls on folders endpoints for a shared item.

Parameters:

sharedLink - shared link.

password - password of the shared link, use null if there is no password

Returns:

BoxFoldersManager

getSharedCommentsManager

public IBoxCommentsManager getSharedCommentsManager(java.lang.String sharedLink,
                                           java.lang.String password)

Get the BoxCommentsManager for shared items, which can be used to make API calls on comments endpoints for a shared item.

Parameters:

sharedLink - shared link.

password - password of the shared link, use null if there is no password

Returns:

BoxFoldersManager

getResourceManagerWithSharedLinkAuth

public IBoxResourceManager getResourceManagerWithSharedLinkAuth(BoxResourceType type,
                                                       java.lang.String sharedLink,
                                                       java.lang.String password)

A generic way to get a resourceManager with shared link auth. Currently only supports file, folder and comment endpoints.

Parameters:

type -

sharedLink -

password -

Returns:

getPluginManager

public IBoxResourceManager getPluginManager(java.lang.String pluginManagerKey)

Get a resource manager plugged in based on the key.

getFoldersManager

public IBoxFoldersManager getFoldersManager()

Returns:

the BoxFoldersManager, which can be used to make API calls on folders endpoints. Note this folders manager only work on the folders you own. if you are trying to make api calls on a shared folder (folder shared to you via shared link), please use getSharedFoldersManager().

getWebLinksManager

public IBoxWebLinksManager getWebLinksManager()

Returns:

the BoxWebLinksManager, which can be used to make API calls on web_links endpoints.

getSearchManager

public IBoxSearchManager getSearchManager()

Returns:

BoxSearchManager through which searches can be performed.

getEventsManager

public IBoxEventsManager getEventsManager()

Returns:

BoxEventsManager through which the Box Events API can be queried.

getCollaborationsManager

public IBoxCollaborationsManager getCollaborationsManager()

Returns:

the collaborationsManager

getCollectionsManager

public IBoxCollectionsManager getCollectionsManager()

Returns:

the collectionsManager

getCommentsManager

public IBoxCommentsManager getCommentsManager()

Returns:

the commentsManager

getUsersManager

public IBoxUsersManager getUsersManager()

Returns:

the usersManager

authenticate

public void authenticate(IAuthData authData)

Get authenticated using a Auth object, this could be a previously stored data.

Parameters:

authData -

authenticate

public void authenticate(IAuthFlowUI authFlowUI,
                boolean autoRefreshOAuth,
                IAuthFlowListener listener)

Get authenticated. Note authentication is done asynchronously and may not finish right after this method. The authentication result should be notified to the IAuthFlowListener parameter.

Parameters:

authFlowUI - UI for the auth(OAuth) flow.

autoRefreshOAuth - whether the OAuth token should be auto refreshed when it expires.

listener - listener listening to the events of the states that this BoxClient gets authenticated. In the end of normal OAuth flow, since it's already done it's duty, this listener is removed so it is not held in memory by BoxClient. In unusual ending of OAuth flow, e.g., your own code forces finish the OAuth flow, this listener may stay binded to BoxClient, call clearBoxClientAuthListener() if you really need to remove it.

getBoxClientAuthenticationListener

protected IAuthFlowListener getBoxClientAuthenticationListener()

setBoxClientAuthListener

protected void setBoxClientAuthListener(IAuthFlowListener listener)

set listener listening to the events of the states that this BoxClient gets authenticateds. Do not make this method public. This is only called internally in authenticate method.

getAuthState

public OAuthDataController.OAuthTokenState getAuthState()

Check authentication state.

Returns:

authentication state

getConfig

public IBoxConfig getConfig()

Get config.

Returns:

config

createResourceHub

protected IBoxResourceHub createResourceHub()

Create a resource hub

Returns:

IBoxResourceHub

createJSONParser

protected IBoxJSONParser createJSONParser(IBoxResourceHub resourceHub)

Create a json parser.

Parameters:

resourceHub -

Returns:

getResourceHub

public IBoxResourceHub getResourceHub()

Get resource hub.

Returns:

Resource hub

getJSONParser

public IBoxJSONParser getJSONParser()

getRestClient

protected IBoxRESTClient getRestClient()

Get rest client.

Returns:

createRestClient

protected static IBoxRESTClient createRestClient()

Create a REST client to make api calls.

Returns:

IBoxRESTClient

createMonitoredRestClient

protected static IBoxRESTClient createMonitoredRestClient(BoxConnectionManagerBuilder.BoxConnectionManager connectionManager)

getSharedItemAuth

public IBoxRequestAuth getSharedItemAuth(java.lang.String sharedLink,
                                java.lang.String password)

Get the authorization needed for shared items.

Parameters:

sharedLink - shared link

password - password(use null if no password at all)

Returns:

IBoxRequestAuth

createAuthDataController

protected IAuthDataController createAuthDataController(java.lang.String clientId,
                                           java.lang.String clientSecret)

Create auth data controller, which maintains auth data and handles auth refresh.

createAuthorization

protected IBoxRequestAuth createAuthorization(IAuthDataController controller)

From auth data controller, generate IBoxRequestAuth, which can be applied to api requests.

getAuth

public IBoxRequestAuth getAuth()

Get the auth object used to make api calls.

Returns:

clearBoxClientAuthListener

public void clearBoxClientAuthListener()

Clear the auth listener so it's not held by BoxClient any more.

onAuthFlowEvent

public void onAuthFlowEvent(IAuthEvent event,
                   IAuthFlowMessage message)

Description copied from interface: IAuthFlowListener

On an event.

Specified by:

onAuthFlowEvent in interface IAuthFlowListener

Parameters:

event - state

message - context message of this event

onAuthFlowMessage

public void onAuthFlowMessage(IAuthFlowMessage message)

Description copied from interface: IAuthFlowListener

On a message.

Specified by:

onAuthFlowMessage in interface IAuthFlowListener

Parameters:

message - message

onAuthFlowException

public void onAuthFlowException(java.lang.Exception e)

Description copied from interface: IAuthFlowListener

On an exception.

Specified by:

onAuthFlowException in interface IAuthFlowListener

Parameters:

e - exception

getOAuthTokenFromMessage

protected BoxOAuthToken getOAuthTokenFromMessage(IAuthFlowMessage message)