com.box.sdk

Class BoxUser

Object

BoxResource

BoxCollaborator

BoxUser

@BoxResourceType(value="user")
public class BoxUser
extends BoxCollaborator

Represents a Box user account.

Unless otherwise noted, the methods in this class can throw an unchecked BoxAPIException (unchecked meaning that the compiler won't force you to handle it) if an error occurs. If you wish to implement custom error handling for errors related to the Box REST API, you should capture this exception explicitly.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	BoxUser.Info Contains information about a BoxUser.
static class	BoxUser.Role Enumerates the possible roles that a user can have within an enterprise.
static class	BoxUser.Status Enumerates the possible statuses that a user's account can have.

Nested classes/interfaces inherited from class BoxCollaborator

BoxCollaborator.CollaboratorType, BoxCollaborator.GroupType

Field Summary

Fields

Modifier and Type	Field and Description
static String[]	ALL_FIELDS An array of all possible file fields that can be requested when calling getInfo(String...).
static URLTemplate	EMAIL_ALIAS_URL_TEMPLATE E-Mail Alias URL Template.
static URLTemplate	EMAIL_ALIASES_URL_TEMPLATE E-Mail Aliases URL Template.
static URLTemplate	GET_ME_URL Get Me URL Template.
static URLTemplate	MOVE_FOLDER_TO_USER_TEMPLATE Move Folder To User Template.
static URLTemplate	USER_AVATAR_TEMPLATE User Avatar Template.
static URLTemplate	USER_MEMBERSHIPS_URL_TEMPLATE User Memberships URL Template.
static URLTemplate	USER_URL_TEMPLATE User URL Template.
static URLTemplate	USERS_URL_TEMPLATE Users URL Template.

Constructor Summary

Constructors

Constructor and Description
BoxUser(BoxAPIConnection api, String id) Constructs a BoxUser for a user with a given ID.

Method Summary

Modifier and Type	Method and Description
EmailAlias	addEmailAlias(String email) Adds a new email alias to this user's account.
EmailAlias	addEmailAlias(String email, boolean isConfirmed) Adds a new email alias to this user's account and confirms it without user interaction.
static BoxUser.Info	createAppUser(BoxAPIConnection api, String name, CreateUserParams params, String... fields) Provisions a new app user in an enterprise with additional user information using Box Developer Edition.
static BoxUser.Info	createAppUser(BoxAPIConnection api, String name, String... fields) Provisions a new app user in an enterprise using Box Developer Edition.
static BoxUser.Info	createEnterpriseUser(BoxAPIConnection api, String login, String name, CreateUserParams params, String... fields) Provisions a new user in an enterprise with additional user information.
static BoxUser.Info	createEnterpriseUser(BoxAPIConnection api, String login, String name, String... fields) Provisions a new user in an enterprise.
void	delete() Deletes a user from an enterprise account.
void	delete(boolean notifyUser, boolean force) Deletes a user from an enterprise account.
void	deleteAvatar() Removes avatar from user account.
void	deleteEmailAlias(String emailAliasID) Deletes an email alias from this user's account.
void	downloadAvatar(OutputStream outputStream) Writes avatar into specified OutputStream
static Iterable<BoxUser.Info>	getAllEnterpriseOrExternalUsers(BoxAPIConnection api, String filterTerm, boolean usemarker, String marker, String... fields) Gets any managed users that match the filter term as well as any external users that match the filter term.
static Iterable<BoxUser.Info>	getAllEnterpriseOrExternalUsers(BoxAPIConnection api, String filterTerm, String... fields) Gets any managed users that match the filter term as well as any external users that match the filter term.
static Iterable<BoxUser.Info>	getAllEnterpriseUsers(BoxAPIConnection api) Returns an iterable containing all the enterprise users.
static Iterable<BoxUser.Info>	getAllEnterpriseUsers(BoxAPIConnection api, boolean usemarker, String marker) Returns an iterable containing all the enterprise users.
static Iterable<BoxUser.Info>	getAllEnterpriseUsers(BoxAPIConnection api, String filterTerm, boolean usemarker, String marker, String... fields) Returns an iterable containing all the enterprise users that matches the filter and specifies which child fields to retrieve from the API.
static Iterable<BoxUser.Info>	getAllEnterpriseUsers(BoxAPIConnection api, String filterTerm, String... fields) Returns an iterable containing all the enterprise users that matches the filter and specifies which child fields to retrieve from the API.
Iterable<BoxGroupMembership.Info>	getAllMemberships(String... fields) Gets information about all of the group memberships for this user as iterable with paging support.
static Iterable<BoxUser.Info>	getAppUsersByExternalAppUserID(BoxAPIConnection api, String externalAppUserId, boolean usemarker, String marker, String... fields) Gets any app users that has an exact match with the externalAppUserId term using marker based pagination.
static Iterable<BoxUser.Info>	getAppUsersByExternalAppUserID(BoxAPIConnection api, String externalAppUserId, String... fields) Gets any app users that has an exact match with the externalAppUserId term.
InputStream	getAvatar() Deprecated. This method loads whole avatar image to memory. Use downloadAvatar(OutputStream) to store avatar in file or memory. That method uses very small buffer to store bytes in memory.
static BoxUser	getCurrentUser(BoxAPIConnection api) Gets the current user.
Collection<EmailAlias>	getEmailAliases() Gets a collection of all the email aliases for this user.
static Iterable<BoxUser.Info>	getExternalUsers(BoxAPIConnection api, String filterTerm, boolean usemarker, String marker, String... fields) Gets a limited set of information about an external user.
static Iterable<BoxUser.Info>	getExternalUsers(BoxAPIConnection api, String filterTerm, String... fields) Gets a limited set of information about an external user.
BoxUser.Info	getInfo(String... fields) Gets information about this user.
Collection<BoxGroupMembership.Info>	getMemberships() Gets information about all of the group memberships for this user.
BoxFolder.Info	transferContent(String destinationUserID) Moves all the owned content from within one user’s folder into a new folder in another user's account.
void	updateInfo(BoxUser.Info info, String... fields) Updates the information about this user with any info fields that have been modified locally.
AvatarUploadResponse	uploadAvatar(File file) Upload avatar image to user account.
AvatarUploadResponse	uploadAvatar(File file, ProgressListener progressListener) Upload avatar image to user account.
AvatarUploadResponse	uploadAvatar(InputStream content, String fileName) Upload avatar image to user account.
AvatarUploadResponse	uploadAvatar(InputStream content, String fileName, ProgressListener progressListener) Upload avatar image to user account.

Methods inherited from class BoxResource

equals, getAPI, getID, getResourceType, hashCode

Methods inherited from class Object

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

Field Detail

ALL_FIELDS

public static final String[] ALL_FIELDS

An array of all possible file fields that can be requested when calling getInfo(String...).

USER_URL_TEMPLATE

public static final URLTemplate USER_URL_TEMPLATE

User URL Template.

GET_ME_URL

public static final URLTemplate GET_ME_URL

Get Me URL Template.

USERS_URL_TEMPLATE

public static final URLTemplate USERS_URL_TEMPLATE

Users URL Template.

USER_MEMBERSHIPS_URL_TEMPLATE

public static final URLTemplate USER_MEMBERSHIPS_URL_TEMPLATE

User Memberships URL Template.

EMAIL_ALIAS_URL_TEMPLATE

public static final URLTemplate EMAIL_ALIAS_URL_TEMPLATE

E-Mail Alias URL Template.

EMAIL_ALIASES_URL_TEMPLATE

public static final URLTemplate EMAIL_ALIASES_URL_TEMPLATE

E-Mail Aliases URL Template.

MOVE_FOLDER_TO_USER_TEMPLATE

public static final URLTemplate MOVE_FOLDER_TO_USER_TEMPLATE

Move Folder To User Template.

USER_AVATAR_TEMPLATE

public static final URLTemplate USER_AVATAR_TEMPLATE

User Avatar Template.

Constructor Detail

BoxUser

public BoxUser(BoxAPIConnection api,
               String id)

Constructs a BoxUser for a user with a given ID.

Parameters:

api - the API connection to be used by the user.

id - the ID of the user.

Method Detail

createAppUser

public static BoxUser.Info createAppUser(BoxAPIConnection api,
                                         String name,
                                         String... fields)

Provisions a new app user in an enterprise using Box Developer Edition.

Parameters:

api - the API connection to be used by the created user.

name - the name of the user.

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

the created user's info.

createAppUser

public static BoxUser.Info createAppUser(BoxAPIConnection api,
                                         String name,
                                         CreateUserParams params,
                                         String... fields)

Provisions a new app user in an enterprise with additional user information using Box Developer Edition.

Parameters:

api - the API connection to be used by the created user.

name - the name of the user.

params - additional user information.

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

the created user's info.

createEnterpriseUser

public static BoxUser.Info createEnterpriseUser(BoxAPIConnection api,
                                                String login,
                                                String name,
                                                String... fields)

Provisions a new user in an enterprise.

Parameters:

api - the API connection to be used by the created user.

login - the email address the user will use to login.

name - the name of the user.

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

the created user's info.

createEnterpriseUser

public static BoxUser.Info createEnterpriseUser(BoxAPIConnection api,
                                                String login,
                                                String name,
                                                CreateUserParams params,
                                                String... fields)

Provisions a new user in an enterprise with additional user information.

Parameters:

api - the API connection to be used by the created user.

login - the email address the user will use to login.

name - the name of the user.

params - additional user information.

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

the created user's info.

getCurrentUser

public static BoxUser getCurrentUser(BoxAPIConnection api)

Gets the current user.

Parameters:

api - the API connection of the current user.

Returns:

the current user.

getAllEnterpriseUsers

public static Iterable<BoxUser.Info> getAllEnterpriseUsers(BoxAPIConnection api)

Returns an iterable containing all the enterprise users.

Parameters:

api - the API connection to be used when retrieving the users.

Returns:

an iterable containing all the enterprise users.

getAllEnterpriseUsers

public static Iterable<BoxUser.Info> getAllEnterpriseUsers(BoxAPIConnection api,
                                                           boolean usemarker,
                                                           String marker)

Returns an iterable containing all the enterprise users. Uses marker based pagination.

Parameters:

api - the API connection to be used when retrieving the users.

usemarker - Boolean that determines whether to use marker based pagination.

marker - The marker at which the iterator will begin.

Returns:

an iterable containing all the enterprise users.

getAllEnterpriseUsers

public static Iterable<BoxUser.Info> getAllEnterpriseUsers(BoxAPIConnection api,
                                                           String filterTerm,
                                                           String... fields)

Returns an iterable containing all the enterprise users that matches the filter and specifies which child fields to retrieve from the API.

Parameters:

api - the API connection to be used when retrieving the users.

filterTerm - used to filter the results to only users starting with this string in either the name or the login. Can be null to not filter the results.

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

an iterable containing all the enterprise users that matches the filter.

getAllEnterpriseUsers

public static Iterable<BoxUser.Info> getAllEnterpriseUsers(BoxAPIConnection api,
                                                           String filterTerm,
                                                           boolean usemarker,
                                                           String marker,
                                                           String... fields)

Returns an iterable containing all the enterprise users that matches the filter and specifies which child fields to retrieve from the API. Uses marker based pagination.

Parameters:

api - the API connection to be used when retrieving the users.

filterTerm - used to filter the results to only users starting with this string in either the name or the login. Can be null to not filter the results.

usemarker - Boolean that determines whether to use marker based pagination.

marker - The marker at which the iterator will begin.

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

an iterable containing all the enterprise users that matches the filter.

getExternalUsers

public static Iterable<BoxUser.Info> getExternalUsers(BoxAPIConnection api,
                                                      String filterTerm,
                                                      String... fields)

Gets a limited set of information about an external user. (A user collaborating on content owned by the enterprise). Note: Only fields the user has permission to see will be returned with values. Other fields will return a value of null.

Parameters:

api - the API connection to be used when retrieving the users.

filterTerm - used to filter the results to only users matching the given login. This does exact match only, so if no filter term is passed in, nothing will be returned.

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

an iterable containing external users matching the given email

getExternalUsers

public static Iterable<BoxUser.Info> getExternalUsers(BoxAPIConnection api,
                                                      String filterTerm,
                                                      boolean usemarker,
                                                      String marker,
                                                      String... fields)

Gets a limited set of information about an external user. (A user collaborating on content owned by the enterprise). Note: Only fields the user has permission to see will be returned with values. Other fields will return a value of null. Uses marker based pagination.

Parameters:

api - the API connection to be used when retrieving the users.

filterTerm - used to filter the results to only users matching the given login. This does exact match only, so if no filter term is passed in, nothing will be returned.

usemarker - Boolean that determines whether to use marker based pagination.

marker - The marker at which the iterator will begin.

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

an iterable containing external users matching the given email

getAllEnterpriseOrExternalUsers

public static Iterable<BoxUser.Info> getAllEnterpriseOrExternalUsers(BoxAPIConnection api,
                                                                     String filterTerm,
                                                                     String... fields)

Gets any managed users that match the filter term as well as any external users that match the filter term. For managed users it matches any users names or emails that start with the term. For external, it only does full match on email. This method is ideal to use in the case where you have a full email for a user and you don't know if they're managed or external.

Parameters:

api - the API connection to be used when retrieving the users.

filterTerm - The filter term to lookup users by (login for external, login or name for managed)

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

an iterable containing users matching the given email

getAllEnterpriseOrExternalUsers

public static Iterable<BoxUser.Info> getAllEnterpriseOrExternalUsers(BoxAPIConnection api,
                                                                     String filterTerm,
                                                                     boolean usemarker,
                                                                     String marker,
                                                                     String... fields)

Gets any managed users that match the filter term as well as any external users that match the filter term. For managed users it matches any users names or emails that start with the term. For external, it only does full match on email. This method is ideal to use in the case where you have a full email for a user and you don't know if they're managed or external. Uses marker based pagination.

Parameters:

api - the API connection to be used when retrieving the users.

filterTerm - The filter term to lookup users by (login for external, login or name for managed)

usemarker - Boolean that determines whether to use marker based pagination.

marker - The marker at which the iterator will begin.

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

an iterable containing users matching the given email

getAppUsersByExternalAppUserID

public static Iterable<BoxUser.Info> getAppUsersByExternalAppUserID(BoxAPIConnection api,
                                                                    String externalAppUserId,
                                                                    String... fields)

Gets any app users that has an exact match with the externalAppUserId term.

Parameters:

api - the API connection to be used when retrieving the users.

externalAppUserId - the external app user id that has been set for app user

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

an iterable containing users matching the given email

getAppUsersByExternalAppUserID

public static Iterable<BoxUser.Info> getAppUsersByExternalAppUserID(BoxAPIConnection api,
                                                                    String externalAppUserId,
                                                                    boolean usemarker,
                                                                    String marker,
                                                                    String... fields)

Gets any app users that has an exact match with the externalAppUserId term using marker based pagination.

Parameters:

api - the API connection to be used when retrieving the users.

externalAppUserId - the external app user id that has been set for app user

usemarker - Boolean that determines whether to use marker based pagination.

marker - The marker at which the iterator will begin.

fields - the fields to retrieve. Leave this out for the standard fields.

Returns:

an iterable containing users matching the given email

getInfo

public BoxUser.Info getInfo(String... fields)

Gets information about this user.

Parameters:

fields - the optional fields to retrieve.

Returns:

info about this user.

getMemberships

public Collection<BoxGroupMembership.Info> getMemberships()

Gets information about all of the group memberships for this user. Does not support paging.

Note: This method is only available to enterprise admins.

Returns:

a collection of information about the group memberships for this user.

getAllMemberships

public Iterable<BoxGroupMembership.Info> getAllMemberships(String... fields)

Gets information about all of the group memberships for this user as iterable with paging support.

Parameters:

fields - the fields to retrieve.

Returns:

an iterable with information about the group memberships for this user.

addEmailAlias

public EmailAlias addEmailAlias(String email)

Adds a new email alias to this user's account.

Parameters:

email - the email address to add as an alias.

Returns:

the newly created email alias.

addEmailAlias

public EmailAlias addEmailAlias(String email,
                                boolean isConfirmed)

Adds a new email alias to this user's account and confirms it without user interaction. This functionality is only available for enterprise admins.

Parameters:

email - the email address to add as an alias.

isConfirmed - whether or not the email alias should be automatically confirmed.

Returns:

the newly created email alias.

deleteEmailAlias

public void deleteEmailAlias(String emailAliasID)

Deletes an email alias from this user's account.

The IDs of the user's email aliases can be found by calling getEmailAliases().

Parameters:

emailAliasID - the ID of the email alias to delete.

getEmailAliases

public Collection<EmailAlias> getEmailAliases()

Gets a collection of all the email aliases for this user.

Note that the user's primary login email is not included in the collection of email aliases.

Returns:

a collection of all the email aliases for this user.

delete

public void delete(boolean notifyUser,
                   boolean force)

Deletes a user from an enterprise account.

Parameters:

notifyUser - whether or not to send an email notification to the user that their account has been deleted.

force - whether or not this user should be deleted even if they still own files.

delete

public void delete()

Deletes a user from an enterprise account. Uses API default values to determine if request should be forced and if user should be notified.

updateInfo

public void updateInfo(BoxUser.Info info,
                       String... fields)

Updates the information about this user with any info fields that have been modified locally.

Note: This method is only available to enterprise admins.

Parameters:

info - info the updated info.

fields - the fields to retrieve. Leave this out for the standard fields.

transferContent

public BoxFolder.Info transferContent(String destinationUserID)

Moves all the owned content from within one user’s folder into a new folder in another user's account. You can move folders across users as long as the you have administrative permissions and the 'source' user owns the folders. Per the documentation at the link below, this will move everything from the root folder, as this is currently the only mode of operation supported.

See also https://developer.box.com/en/reference/put-users-id-folders-id/

Parameters:

destinationUserID - the user id of the user that you wish to transfer content to.

Returns:

info for the newly created folder.

downloadAvatar

public void downloadAvatar(OutputStream outputStream)

Writes avatar into specified OutputStream

Parameters:

outputStream - Stream where to write avatar.

getAvatar

public InputStream getAvatar()

Deprecated. This method loads whole avatar image to memory. Use downloadAvatar(OutputStream) to store avatar in file or memory. That method uses very small buffer to store bytes in memory.

Retrieves the avatar of a user as an InputStream.

Returns:

InputStream representing the user avater.

uploadAvatar

public AvatarUploadResponse uploadAvatar(File file)

Upload avatar image to user account. Supported formats are JPG and PNG. The image size cannot exceed 1024 * 1024 pixels or 1MB.

Parameters:

file - File containg avatar image.

Returns:

Avatar creation response.

uploadAvatar

public AvatarUploadResponse uploadAvatar(File file,
                                         ProgressListener progressListener)

Upload avatar image to user account. Supported formats are JPG and PNG. The image size cannot exceed 1024 * 1024 pixels or 1MB.

Parameters:

file - File containg avatar image.

progressListener - ProgressListener set if you want to track upload progress

Returns:

Avatar creation response.

uploadAvatar

public AvatarUploadResponse uploadAvatar(InputStream content,
                                         String fileName)

Upload avatar image to user account. Supported formats are JPG and PNG. The image size cannot exceed 1024 * 1024 pixels or 1MB.

Parameters:

content - InputStream containing image data

fileName - file name with extention what will be used to determine content type

Returns:

Avatar creation response.

uploadAvatar

public AvatarUploadResponse uploadAvatar(InputStream content,
                                         String fileName,
                                         ProgressListener progressListener)

Upload avatar image to user account. Supported formats are JPG and PNG. The image size cannot exceed 1024 * 1024 pixels or 1MB.

Parameters:

content - InputStream containing image data

fileName - file name with extention what will be used to determine content type

progressListener - ProgressListener set if you want to track upload progress

Returns:

Avatar creation response.

deleteAvatar

public void deleteAvatar()

Removes avatar from user account.