com.box.sdk

Class BoxFile

Object

BoxResource

BoxItem

BoxFile

@BoxResourceType(value="file")
public class BoxFile
extends BoxItem

Represents an individual file on Box. This class can be used to download a file's contents, upload new versions, and perform other common file operations (move, copy, delete, etc.).

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	BoxFile.Info Contains information about a BoxFile.
static class	BoxFile.Permission Enumerates the possible permissions that a user can have on a file.
static class	BoxFile.ThumbnailFileType Used to specify what filetype to request for a file thumbnail.

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

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
BoxComment.Info	addComment(String message) Adds a comment to this file.
BoxTask.Info	addTask(BoxTask.Action action, String message, Date dueAt) Adds a new task to this file.
BoxWebHook.Info	addWebHook(URL address, BoxWebHook.Trigger... triggers) Adds new BoxWebHook to this BoxFile.
BoxWatermark	applyWatermark() Used to apply or update the watermark for the file.
void	canUploadVersion(String name, long fileSize, String parentID) Checks if the file can be successfully uploaded by using the preflight check.
BoxCollaboration.Info	collaborate(BoxCollaborator collaborator, BoxCollaboration.Role role, Boolean notify, Boolean canViewPath) Adds a collaborator to this file.
BoxCollaboration.Info	collaborate(String email, BoxCollaboration.Role role, Boolean notify, Boolean canViewPath) Adds a collaborator to this folder.
BoxFile.Info	copy(BoxFolder destination) Copies this item to another folder.
BoxFile.Info	copy(BoxFolder destination, String newName) Copies this item to another folder and gives it a new name.
Metadata	createMetadata(Metadata metadata) Creates metadata on this file in the global properties template.
Metadata	createMetadata(String typeName, Metadata metadata) Creates metadata on this file in the specified template type.
Metadata	createMetadata(String typeName, String scope, Metadata metadata) Creates metadata on this file in the specified template type.
BoxSharedLink	createSharedLink(BoxSharedLink.Access access, Date unshareDate, BoxSharedLink.Permissions permissions) Creates a new shared link for this item.
BoxFileUploadSession.Info	createUploadSession(long fileSize) Creates an upload session to create a new version of a file in chunks.
void	delete() Deletes this file by moving it to the trash.
void	deleteMetadata() Deletes the file properties metadata.
void	deleteMetadata(String typeName) Deletes the file metadata of specified template type.
void	deleteMetadata(String typeName, String scope) Deletes the file metadata of specified template type.
void	download(OutputStream output) Downloads the contents of this file to a given OutputStream.
void	download(OutputStream output, ProgressListener listener) Downloads the contents of this file to a given OutputStream while reporting the progress to a ProgressListener.
void	downloadRange(OutputStream output, long offset) Downloads a part of this file's contents, starting at specified byte offset.
void	downloadRange(OutputStream output, long rangeStart, long rangeEnd) Downloads a part of this file's contents, starting at rangeStart and stopping at rangeEnd.
void	downloadRange(OutputStream output, long rangeStart, long rangeEnd, ProgressListener listener) Downloads a part of this file's contents, starting at rangeStart and stopping at rangeEnd, while reporting the progress to a ProgressListener.
BoxResourceIterable<BoxCollaboration.Info>	getAllFileCollaborations(String... fields) Used to retrieve all collaborations associated with the item.
Iterable<Metadata>	getAllMetadata(String... fields) Used to retrieve all metadata associated with the file.
List<BoxComment.Info>	getComments() Gets a list of any comments on this file.
URL	getDownloadURL() Gets an expiring URL for downloading a file directly from Box.
BoxFile.Info	getInfo() Gets information about this item.
BoxFile.Info	getInfo(String... fields) Gets information about this item that's limited to a list of specified fields.
protected URL	getItemURL()
Metadata	getMetadata() Gets the file properties metadata.
Metadata	getMetadata(String typeName) Gets the file metadata of specified template type.
Metadata	getMetadata(String typeName, String scope) Gets the file metadata of specified template type.
URL	getPreviewLink() Gets an expiring URL for creating an embedded preview session.
List<BoxTask.Info>	getTasks() Gets a list of any tasks on this file.
byte[]	getThumbnail(BoxFile.ThumbnailFileType fileType, int minWidth, int minHeight, int maxWidth, int maxHeight) Retrieves a thumbnail, or smaller image representation, of this file.
Collection<BoxFileVersion>	getVersions() Gets any previous versions of this file.
BoxWatermark	getWatermark(String... fields) Used to retrieve the watermark for the file.
BoxLock	lock(Date expiresAt) Locks a file.
BoxLock	lock(Date expiresAt, boolean isDownloadPrevented) Locks a file.
BoxItem.Info	move(BoxFolder destination) Moves this item to another folder.
BoxItem.Info	move(BoxFolder destination, String newName) Moves this item to another folder and gives it a new name.
void	removeWatermark() Removes a watermark from the file.
void	rename(String newName) Renames this file.
BoxFile.Info	setCollections(BoxCollection... collections) Sets the collections that this item belongs to.
void	unlock() Unlocks a file.
void	updateInfo(BoxFile.Info info) Updates the information about this file with any info fields that have been modified locally.
Metadata	updateMetadata(Metadata metadata) Updates the file metadata.
BoxFile.Info	uploadLargeFile(InputStream inputStream, long fileSize) Creates a new version of a file.
BoxFile.Info	uploadLargeFile(InputStream inputStream, long fileSize, int nParallelConnections, long timeOut, TimeUnit unit) Creates a new version of a file using specified number of parallel http connections.
void	uploadVersion(InputStream fileContent) Uploads a new version of this file, replacing the current version.
void	uploadVersion(InputStream fileContent, Date modified, long fileSize, ProgressListener listener) Uploads a new version of this file, replacing the current version, while reporting the progress to a ProgressListener.
void	uploadVersion(InputStream fileContent, String fileContentSHA1) Uploads a new version of this file, replacing the current version.
void	uploadVersion(InputStream fileContent, String fileContentSHA1, Date modified) Uploads a new version of this file, replacing the current version.
void	uploadVersion(InputStream fileContent, String fileContentSHA1, Date modified, long fileSize, ProgressListener listener) Uploads a new version of this file, replacing the current version, while reporting the progress to a ProgressListener.

Methods inherited from class BoxItem

applyWatermark, getSharedItem, getSharedItem, getWatermark, removeWatermark

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

Constructor Detail

BoxFile

public BoxFile(BoxAPIConnection api,
               String id)

Constructs a BoxFile for a file with a given ID.

Parameters:

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

id - the ID of the file.

Method Detail

getItemURL

protected URL getItemURL()

Overrides:

getItemURL in class BoxItem

Returns:

URL for the current object, constructed as base URL pus an item specifier.

createSharedLink

public BoxSharedLink createSharedLink(BoxSharedLink.Access access,
                                      Date unshareDate,
                                      BoxSharedLink.Permissions permissions)

Description copied from class: BoxItem

Creates a new shared link for this item.

This method is a convenience method for manually creating a new shared link and applying it to this item with BoxItem.Info.setSharedLink(com.box.sdk.BoxSharedLink). You may want to create the shared link manually so that it can be updated along with other changes to the item's info in a single network request, giving a boost to performance.

Specified by:

createSharedLink in class BoxItem

Parameters:

access - the access level of the shared link.

unshareDate - the date and time at which the link will expire. Can be null to create a non-expiring link.

permissions - the permissions of the shared link. Can be null to use the default permissions.

Returns:

the created shared link.

addWebHook

public BoxWebHook.Info addWebHook(URL address,
                                  BoxWebHook.Trigger... triggers)

Adds new BoxWebHook to this BoxFile.

Parameters:

address - BoxWebHook.Info.getAddress()

triggers - BoxWebHook.Info.getTriggers()

Returns:

created BoxWebHook.Info

addComment

public BoxComment.Info addComment(String message)

Adds a comment to this file. The message can contain @mentions by using the string @[userid:username] anywhere within the message, where userid and username are the ID and username of the person being mentioned.

Parameters:

message - the comment's message.

Returns:

information about the newly added comment.

See Also:

the tagged_message field for including @mentions.

addTask

public BoxTask.Info addTask(BoxTask.Action action,
                            String message,
                            Date dueAt)

Adds a new task to this file. The task can have an optional message to include, and a due date.

Parameters:

action - the action the task assignee will be prompted to do.

message - an optional message to include with the task.

dueAt - the day at which this task is due.

Returns:

information about the newly added task.

getDownloadURL

public URL getDownloadURL()

Gets an expiring URL for downloading a file directly from Box. This can be user, for example, for sending as a redirect to a browser to cause the browser to download the file directly from Box.

Returns:

the temporary download URL

download

public void download(OutputStream output)

Downloads the contents of this file to a given OutputStream.

Parameters:

output - the stream to where the file will be written.

download

public void download(OutputStream output,
                     ProgressListener listener)

Downloads the contents of this file to a given OutputStream while reporting the progress to a ProgressListener.

Parameters:

output - the stream to where the file will be written.

listener - a listener for monitoring the download's progress.

downloadRange

public void downloadRange(OutputStream output,
                          long offset)

Downloads a part of this file's contents, starting at specified byte offset.

Parameters:

output - the stream to where the file will be written.

offset - the byte offset at which to start the download.

downloadRange

public void downloadRange(OutputStream output,
                          long rangeStart,
                          long rangeEnd)

Downloads a part of this file's contents, starting at rangeStart and stopping at rangeEnd.

Parameters:

output - the stream to where the file will be written.

rangeStart - the byte offset at which to start the download.

rangeEnd - the byte offset at which to stop the download.

downloadRange

public void downloadRange(OutputStream output,
                          long rangeStart,
                          long rangeEnd,
                          ProgressListener listener)

Downloads a part of this file's contents, starting at rangeStart and stopping at rangeEnd, while reporting the progress to a ProgressListener.

Parameters:

output - the stream to where the file will be written.

rangeStart - the byte offset at which to start the download.

rangeEnd - the byte offset at which to stop the download.

listener - a listener for monitoring the download's progress.

copy

public BoxFile.Info copy(BoxFolder destination)

Description copied from class: BoxItem

Copies this item to another folder.

Specified by:

copy in class BoxItem

Parameters:

destination - the destination folder.

Returns:

info about the copied item.

copy

public BoxFile.Info copy(BoxFolder destination,
                         String newName)

Description copied from class: BoxItem

Copies this item to another folder and gives it a new name. If the destination is the same folder as the item's current parent, then newName must be a new, unique name.

Specified by:

copy in class BoxItem

Parameters:

destination - the destination folder.

newName - a new name for the copied item.

Returns:

info about the copied item.

delete

public void delete()

Deletes this file by moving it to the trash.

move

public BoxItem.Info move(BoxFolder destination)

Description copied from class: BoxItem

Moves this item to another folder.

Specified by:

move in class BoxItem

Parameters:

destination - the destination folder.

Returns:

info about the moved item.

move

public BoxItem.Info move(BoxFolder destination,
                         String newName)

Description copied from class: BoxItem

Moves this item to another folder and gives it a new name.

Specified by:

move in class BoxItem

Parameters:

destination - the destination folder.

newName - a new name for the moved item.

Returns:

info about the moved item.

rename

public void rename(String newName)

Renames this file.

Parameters:

newName - the new name of the file.

getInfo

public BoxFile.Info getInfo()

Description copied from class: BoxItem

Gets information about this item.

Specified by:

getInfo in class BoxItem

Returns:

info about this item.

getInfo

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

Description copied from class: BoxItem

Gets information about this item that's limited to a list of specified fields.

Specified by:

getInfo in class BoxItem

Parameters:

fields - the fields to retrieve.

Returns:

info about this item containing only the specified fields.

updateInfo

public void updateInfo(BoxFile.Info info)

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

The only fields that will be updated are the ones that have been modified locally. For example, the following code won't update any information (or even send a network request) since none of the info's fields were changed:

BoxFile file = new File(api, id);
 BoxFile.Info info = file.getInfo();
 file.updateInfo(info);

Parameters:

info - the updated info.

getVersions

public Collection<BoxFileVersion> getVersions()

Gets any previous versions of this file. Note that only users with premium accounts will be able to retrieve previous versions of their files.

Returns:

a list of previous file versions.

canUploadVersion

public void canUploadVersion(String name,
                             long fileSize,
                             String parentID)

Checks if the file can be successfully uploaded by using the preflight check.

Parameters:

name - the name to give the uploaded file or null to use existing name.

fileSize - the size of the file used for account capacity calculations.

parentID - the ID of the parent folder that the new version is being uploaded to.

uploadVersion

public void uploadVersion(InputStream fileContent)

Uploads a new version of this file, replacing the current version. Note that only users with premium accounts will be able to view and recover previous versions of the file.

Parameters:

fileContent - a stream containing the new file contents.

uploadVersion

public void uploadVersion(InputStream fileContent,
                          String fileContentSHA1)

Uploads a new version of this file, replacing the current version. Note that only users with premium accounts will be able to view and recover previous versions of the file.

Parameters:

fileContent - a stream containing the new file contents.

fileContentSHA1 - a string containing the SHA1 hash of the new file contents.

uploadVersion

public void uploadVersion(InputStream fileContent,
                          String fileContentSHA1,
                          Date modified)

Uploads a new version of this file, replacing the current version. Note that only users with premium accounts will be able to view and recover previous versions of the file.

Parameters:

fileContent - a stream containing the new file contents.

fileContentSHA1 - a string containing the SHA1 hash of the new file contents.

modified - the date that the new version was modified.

uploadVersion

public void uploadVersion(InputStream fileContent,
                          Date modified,
                          long fileSize,
                          ProgressListener listener)

Uploads a new version of this file, replacing the current version, while reporting the progress to a ProgressListener. Note that only users with premium accounts will be able to view and recover previous versions of the file.

Parameters:

fileContent - a stream containing the new file contents.

modified - the date that the new version was modified.

fileSize - the size of the file used for determining the progress of the upload.

listener - a listener for monitoring the upload's progress.

uploadVersion

public void uploadVersion(InputStream fileContent,
                          String fileContentSHA1,
                          Date modified,
                          long fileSize,
                          ProgressListener listener)

Uploads a new version of this file, replacing the current version, while reporting the progress to a ProgressListener. Note that only users with premium accounts will be able to view and recover previous versions of the file.

Parameters:

fileContent - a stream containing the new file contents.

fileContentSHA1 - the SHA1 hash of the file contents. will be sent along in the Content-MD5 header

modified - the date that the new version was modified.

fileSize - the size of the file used for determining the progress of the upload.

listener - a listener for monitoring the upload's progress.

getPreviewLink

public URL getPreviewLink()

Gets an expiring URL for creating an embedded preview session. The URL will expire after 60 seconds and the preview session will expire after 60 minutes.

Returns:

the expiring preview link

getThumbnail

public byte[] getThumbnail(BoxFile.ThumbnailFileType fileType,
                           int minWidth,
                           int minHeight,
                           int maxWidth,
                           int maxHeight)

Retrieves a thumbnail, or smaller image representation, of this file. Sizes of 32x32, 64x64, 128x128, and 256x256 can be returned in the .png format and sizes of 32x32, 94x94, 160x160, and 320x320 can be returned in the .jpg format.

Parameters:

fileType - either PNG of JPG

minWidth - minimum width

minHeight - minimum height

maxWidth - maximum width

maxHeight - maximum height

Returns:

the byte array of the thumbnail image

getComments

public List<BoxComment.Info> getComments()

Gets a list of any comments on this file.

Returns:

a list of comments on this file.

getTasks

public List<BoxTask.Info> getTasks()

Gets a list of any tasks on this file.

Returns:

a list of tasks on this file.

createMetadata

public Metadata createMetadata(Metadata metadata)

Creates metadata on this file in the global properties template.

Parameters:

metadata - The new metadata values.

Returns:

the metadata returned from the server.

createMetadata

public Metadata createMetadata(String typeName,
                               Metadata metadata)

Creates metadata on this file in the specified template type.

Parameters:

typeName - the metadata template type name.

metadata - the new metadata values.

Returns:

the metadata returned from the server.

createMetadata

public Metadata createMetadata(String typeName,
                               String scope,
                               Metadata metadata)

Creates metadata on this file in the specified template type.

Parameters:

typeName - the metadata template type name.

scope - the metadata scope (global or enterprise).

metadata - the new metadata values.

Returns:

the metadata returned from the server.

lock

public BoxLock lock(Date expiresAt)

Locks a file.

Parameters:

expiresAt - expiration date of the lock.

Returns:

the lock returned from the server.

lock

public BoxLock lock(Date expiresAt,
                    boolean isDownloadPrevented)

Locks a file.

Parameters:

expiresAt - expiration date of the lock.

isDownloadPrevented - is downloading of file prevented when locked.

Returns:

the lock returned from the server.

unlock

public void unlock()

Unlocks a file.

getAllMetadata

public Iterable<Metadata> getAllMetadata(String... fields)

Used to retrieve all metadata associated with the file.

Parameters:

fields - the optional fields to retrieve.

Returns:

An iterable of metadata instances associated with the file.

getMetadata

public Metadata getMetadata()

Gets the file properties metadata.

Returns:

the metadata returned from the server.

getMetadata

public Metadata getMetadata(String typeName)

Gets the file metadata of specified template type.

Parameters:

typeName - the metadata template type name.

Returns:

the metadata returned from the server.

getMetadata

public Metadata getMetadata(String typeName,
                            String scope)

Gets the file metadata of specified template type.

Parameters:

typeName - the metadata template type name.

scope - the metadata scope (global or enterprise).

Returns:

the metadata returned from the server.

updateMetadata

public Metadata updateMetadata(Metadata metadata)

Updates the file metadata.

Parameters:

metadata - the new metadata values.

Returns:

the metadata returned from the server.

deleteMetadata

public void deleteMetadata()

Deletes the file properties metadata.

deleteMetadata

public void deleteMetadata(String typeName)

Deletes the file metadata of specified template type.

Parameters:

typeName - the metadata template type name.

deleteMetadata

public void deleteMetadata(String typeName,
                           String scope)

Deletes the file metadata of specified template type.

Parameters:

typeName - the metadata template type name.

scope - the metadata scope (global or enterprise).

getWatermark

public BoxWatermark getWatermark(String... fields)

Used to retrieve the watermark for the file. If the file does not have a watermark applied to it, a 404 Not Found will be returned by API.

Parameters:

fields - the fields to retrieve.

Returns:

the watermark associated with the file.

applyWatermark

public BoxWatermark applyWatermark()

Used to apply or update the watermark for the file.

Returns:

the watermark associated with the file.

removeWatermark

public void removeWatermark()

Removes a watermark from the file. If the file did not have a watermark applied to it, a 404 Not Found will be returned by API.

setCollections

public BoxFile.Info setCollections(BoxCollection... collections)

Sets the collections that this item belongs to.

Specified by:

setCollections in class BoxItem

Parameters:

collections - the collections that this item should belong to.

Returns:

info about the item, including the collections it belongs to.

createUploadSession

public BoxFileUploadSession.Info createUploadSession(long fileSize)

Creates an upload session to create a new version of a file in chunks. This will first verify that the version can be created and then open a session for uploading pieces of the file.

Parameters:

fileSize - the size of the file that will be uploaded.

Returns:

the created upload session instance.

uploadLargeFile

public BoxFile.Info uploadLargeFile(InputStream inputStream,
                                    long fileSize)
                             throws InterruptedException,
                                    IOException

Creates a new version of a file.

Parameters:

inputStream - the stream instance that contains the data.

fileSize - the size of the file that will be uploaded.

Returns:

the created file instance.

Throws:

InterruptedException - when a thread execution is interrupted.

IOException - when reading a stream throws exception.

uploadLargeFile

public BoxFile.Info uploadLargeFile(InputStream inputStream,
                                    long fileSize,
                                    int nParallelConnections,
                                    long timeOut,
                                    TimeUnit unit)
                             throws InterruptedException,
                                    IOException

Creates a new version of a file using specified number of parallel http connections.

Parameters:

inputStream - the stream instance that contains the data.

fileSize - the size of the file that will be uploaded.

nParallelConnections - number of parallel http connections to use

timeOut - time to wait before killing the job

unit - time unit for the time wait value

Returns:

the created file instance.

Throws:

InterruptedException - when a thread execution is interrupted.

IOException - when reading a stream throws exception.

collaborate

public BoxCollaboration.Info collaborate(BoxCollaborator collaborator,
                                         BoxCollaboration.Role role,
                                         Boolean notify,
                                         Boolean canViewPath)

Adds a collaborator to this file.

Parameters:

collaborator - the collaborator to add.

role - the role of the collaborator.

notify - determines if the user (or all the users in the group) will receive email notifications.

canViewPath - whether view path collaboration feature is enabled or not.

Returns:

info about the new collaboration.

collaborate

public BoxCollaboration.Info collaborate(String email,
                                         BoxCollaboration.Role role,
                                         Boolean notify,
                                         Boolean canViewPath)

Adds a collaborator to this folder. An email will be sent to the collaborator if they don't already have a Box account.

Parameters:

email - the email address of the collaborator to add.

role - the role of the collaborator.

notify - determines if the user (or all the users in the group) will receive email notifications.

canViewPath - whether view path collaboration feature is enabled or not.

Returns:

info about the new collaboration.

getAllFileCollaborations

public BoxResourceIterable<BoxCollaboration.Info> getAllFileCollaborations(String... fields)

Used to retrieve all collaborations associated with the item.

Parameters:

fields - the optional fields to retrieve.

Returns:

An iterable of metadata instances associated with the item.