com.box.boxjavalibv2

Class BoxClient

java.lang.Object

com.box.boxjavalibv2.dao.BoxBase

com.box.boxjavalibv2.BoxClient

All Implemented Interfaces:

IAuthFlowListener

Direct Known Subclasses:

BoxAndroidClient, MockBoxClient

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 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.
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.
BoxOAuthToken	getAuthData() Get the OAuth data.
OAuthDataController.OAuthTokenState	getAuthState() Check authentication state.
IBoxItemsManager	getBoxItemsManager() Get the BoxItemsManager, which can be used to make API calls on files/folders endpoints.
IBoxCollaborationsManager	getCollaborationsManager()
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()
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.
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 BoxOAuthToken getAuthData()
                          throws AuthFatalFailureException

Get the OAuth data.

Returns:

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().

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

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 auth flow events.

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

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:

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)