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 URLTemplate	ABORT_UPLOAD_SESSION_URL_TEMPLATE Abort Upload Session URL Template.
static URLTemplate	ADD_COLLABORATION_URL Add Collaborations URL Template.
static URLTemplate	ADD_COMMENT_URL_TEMPLATE Add Comment URL Template.
static URLTemplate	ADD_TASK_URL_TEMPLATE Add Task URL Template.
static String[]	ALL_FIELDS An array of all possible file fields that can be requested when calling getInfo(String...).
static String[]	ALL_VERSION_FIELDS An array of all possible version fields that can be requested when calling getVersions(String...).
static URLTemplate	CONTENT_URL_TEMPLATE Content URL Template.
static URLTemplate	COPY_URL_TEMPLATE Copy URL Template.
static URLTemplate	FILE_URL_TEMPLATE File URL Template.
static URLTemplate	GET_ALL_FILE_COLLABORATIONS_URL Get All File Collaborations URL Template.
static URLTemplate	GET_COMMENTS_URL_TEMPLATE Get Comments URL Template.
static URLTemplate	GET_TASKS_URL_TEMPLATE Get Tasks URL Template.
static URLTemplate	GET_THUMBNAIL_JPG_TEMPLATE Get Thumbnail JPG Template.
static URLTemplate	GET_THUMBNAIL_PNG_TEMPLATE Get Thumbnail PNG Template.
static URLTemplate	METADATA_URL_TEMPLATE Metadata URL Template.
static URLTemplate	UPLOAD_SESSION_STATUS_URL_TEMPLATE Upload Session Status URL Template.
static URLTemplate	UPLOAD_SESSION_URL_TEMPLATE Upload Session URL Template.
static URLTemplate	VERSIONS_URL_TEMPLATE Versions URL Template.

Fields inherited from class BoxItem

SHARED_ITEM_URL_TEMPLATE, WATERMARK_URL_TEMPLATE

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
String	addClassification(String classificationType) Adds a metadata classification to the specified file.
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.
BoxTask.Info	addTask(BoxTask.Action action, String message, Date dueAt, BoxTask.CompletionRule completionRule) 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.
boolean	canUploadVersion(String name) Checks if a new version of the file can be uploaded with the specified name.
boolean	canUploadVersion(String name, long fileSize) Checks if a new version of the file can be uploaded with the specified name and size.
BoxCollaboration.Info	collaborate(BoxCollaborator collaborator, BoxCollaboration.Role role, Boolean notify, Boolean canViewPath) Adds a collaborator to this file.
BoxCollaboration.Info	collaborate(BoxCollaborator collaborator, BoxCollaboration.Role role, Boolean notify, Boolean canViewPath, Date expiresAt, Boolean isAccessOnly) Adds a collaborator to this file.
BoxCollaboration.Info	collaborate(String email, BoxCollaboration.Role role, Boolean notify, Boolean canViewPath) Adds a collaborator to this folder.
BoxCollaboration.Info	collaborate(String email, BoxCollaboration.Role role, Boolean notify, Boolean canViewPath, Date expiresAt, Boolean isAccessOnly) 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(BoxSharedLinkRequest sharedLinkRequest) Creates a shared link.
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	deleteClassification() Deletes the classification on the file.
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.
String	getClassification() Gets the classification type for the specified file.
List<BoxComment.Info>	getComments() Gets a list of any comments on this file.
protected URL	getDownloadUrl() Can be used to override the URL used for file download.
URL	getDownloadURL() Gets an expiring URL for downloading a file directly from Box.
BoxFile.Info	getInfo(String... fields) Gets information about this item that's limited to a list of specified fields.
BoxFile.Info	getInfoWithRepresentations(String representationHints, String... fields) Gets information about this item including a specified set of representations.
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.
void	getRepresentationContent(String representationHint, OutputStream output) Fetches the contents of a file representation and writes them to the provided output stream.
void	getRepresentationContent(String representationHint, String assetPath, OutputStream output) Fetches the contents of a file representation with asset path and writes them to the provided output stream.
void	getRepresentationContent(String representationHint, String assetPath, OutputStream output, int maxRetries) Fetches the contents of a file representation with asset path and writes them to the provided output stream.
List<BoxTask.Info>	getTasks(String... fields) Gets a list of any tasks on this file with requested fields.
Collection<BoxFileVersion>	getVersions(String... fields) Gets up to 1000 versions of this file.
PartialCollection<BoxFileVersion>	getVersionsRange(long offset, long limit, String... fields) Retrieves a specific range of versions of this file.
BoxWatermark	getWatermark(String... fields) Used to retrieve the watermark for the file.
BoxLock	lock() Locks a file.
BoxLock	lock(boolean isDownloadPrevented) Locks a 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.
String	setClassification(String classificationType) Attempts to add classification to a file.
BoxFile.Info	setCollections(BoxCollection... collections) Sets the collections that this item belongs to.
Metadata	setMetadata(String templateName, String scope, Metadata metadata) Sets the provided metadata on the file.
void	unlock() Unlocks a file.
String	updateClassification(String classificationType) Updates a metadata classification on the specified 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.
BoxFile.Info	uploadLargeFile(InputStream inputStream, long fileSize, int nParallelConnections, long timeOut, TimeUnit unit, Map<String,String> fileAttributes) Creates a new version of a file using specified number of parallel http connections.
BoxFile.Info	uploadLargeFile(InputStream inputStream, long fileSize, Map<String,String> fileAttributes) Creates a new version of a file.
BoxFile.Info	uploadNewVersion(InputStream fileContent) Uploads a new version of this file, replacing the current version.
BoxFile.Info	uploadNewVersion(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.
BoxFile.Info	uploadNewVersion(InputStream fileContent, String fileContentSHA1) Uploads a new version of this file, replacing the current version.
BoxFile.Info	uploadNewVersion(InputStream fileContent, String fileContentSHA1, Date modified) Uploads a new version of this file, replacing the current version.
BoxFile.Info	uploadNewVersion(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.
BoxFile.Info	uploadNewVersion(InputStream fileContent, String fileContentSHA1, Date modified, String name) Uploads a new version of this file, replacing the current version.
BoxFile.Info	uploadNewVersion(InputStream fileContent, String fileContentSHA1, Date modified, String name, 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(String...).

ALL_VERSION_FIELDS

public static final String[] ALL_VERSION_FIELDS

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

FILE_URL_TEMPLATE

public static final URLTemplate FILE_URL_TEMPLATE

File URL Template.

CONTENT_URL_TEMPLATE

public static final URLTemplate CONTENT_URL_TEMPLATE

Content URL Template.

VERSIONS_URL_TEMPLATE

public static final URLTemplate VERSIONS_URL_TEMPLATE

Versions URL Template.

COPY_URL_TEMPLATE

public static final URLTemplate COPY_URL_TEMPLATE

Copy URL Template.

ADD_COMMENT_URL_TEMPLATE

public static final URLTemplate ADD_COMMENT_URL_TEMPLATE

Add Comment URL Template.

GET_COMMENTS_URL_TEMPLATE

public static final URLTemplate GET_COMMENTS_URL_TEMPLATE

Get Comments URL Template.

METADATA_URL_TEMPLATE

public static final URLTemplate METADATA_URL_TEMPLATE

Metadata URL Template.

ADD_TASK_URL_TEMPLATE

public static final URLTemplate ADD_TASK_URL_TEMPLATE

Add Task URL Template.

GET_TASKS_URL_TEMPLATE

public static final URLTemplate GET_TASKS_URL_TEMPLATE

Get Tasks URL Template.

GET_THUMBNAIL_PNG_TEMPLATE

public static final URLTemplate GET_THUMBNAIL_PNG_TEMPLATE

Get Thumbnail PNG Template.

GET_THUMBNAIL_JPG_TEMPLATE

public static final URLTemplate GET_THUMBNAIL_JPG_TEMPLATE

Get Thumbnail JPG Template.

UPLOAD_SESSION_URL_TEMPLATE

public static final URLTemplate UPLOAD_SESSION_URL_TEMPLATE

Upload Session URL Template.

UPLOAD_SESSION_STATUS_URL_TEMPLATE

public static final URLTemplate UPLOAD_SESSION_STATUS_URL_TEMPLATE

Upload Session Status URL Template.

ABORT_UPLOAD_SESSION_URL_TEMPLATE

public static final URLTemplate ABORT_UPLOAD_SESSION_URL_TEMPLATE

Abort Upload Session URL Template.

ADD_COLLABORATION_URL

public static final URLTemplate ADD_COLLABORATION_URL

Add Collaborations URL Template.

GET_ALL_FILE_COLLABORATIONS_URL

public static final URLTemplate GET_ALL_FILE_COLLABORATIONS_URL

Get All File Collaborations URL Template.

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(BoxSharedLinkRequest sharedLinkRequest)

Creates a shared link.

Parameters:

sharedLinkRequest - Shared link to create

Returns:

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.

addTask

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

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

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.

completionRule - the rule for completing the task.

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.

getDownloadUrl

protected URL getDownloadUrl()

Can be used to override the URL used for file download.

Returns:

URL for file downalod

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

getInfoWithRepresentations

public BoxFile.Info getInfoWithRepresentations(String representationHints,
                                               String... fields)

Gets information about this item including a specified set of representations.

Parameters:

representationHints - hints for representations to be retrieved

fields - the fields to retrieve.

Returns:

info about this item containing only the specified fields, including representations.

See Also:

X-Rep-Hints Header

getRepresentationContent

public void getRepresentationContent(String representationHint,
                                     OutputStream output)

Fetches the contents of a file representation and writes them to the provided output stream.

Parameters:

representationHint - the X-Rep-Hints query for the representation to fetch.

output - the output stream to write the contents to.

See Also:

X-Rep-Hints Header

getRepresentationContent

public void getRepresentationContent(String representationHint,
                                     String assetPath,
                                     OutputStream output)

Fetches the contents of a file representation with asset path and writes them to the provided output stream.

Parameters:

representationHint - the X-Rep-Hints query for the representation to fetch.

assetPath - the path of the asset for representations containing multiple files.

output - the output stream to write the contents to.

See Also:

X-Rep-Hints Header

getRepresentationContent

public void getRepresentationContent(String representationHint,
                                     String assetPath,
                                     OutputStream output,
                                     int maxRetries)

Fetches the contents of a file representation with asset path and writes them to the provided output stream.

Parameters:

representationHint - the X-Rep-Hints query for the representation to fetch.

assetPath - the path of the asset for representations containing multiple files.

output - the output stream to write the contents to.

maxRetries - the maximum number of attempts to call the request for retrieving status information indicating whether the representation has been generated and is ready to fetch. If the number of attempts is exceeded, the method will throw a BoxApiException.

See Also:

X-Rep-Hints Header

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

Gets up to 1000 versions of this file. Note that only users with premium accounts will be able to retrieve previous versions of their files. `fields` parameter is optional, if specified only requested fields will be returned:

 
 new BoxFile(api, file_id).getVersions()       // will return all default fields
 new BoxFile(api, file_id).getVersions("name") // will return only specified fields
 
 

Parameters:

fields - the fields to retrieve. If nothing provided default fields will be returned. You can find list of available fields at ALL_VERSION_FIELDS

Returns:

a list of previous file versions.

getVersionsRange

public PartialCollection<BoxFileVersion> getVersionsRange(long offset,
                                                          long limit,
                                                          String... fields)

Retrieves a specific range of versions of this file.

Parameters:

offset - the index of the first version of this file to retrieve.

limit - the maximum number of versions to retrieve after the offset.

fields - the fields to retrieve.

Returns:

a partial collection containing the specified range of versions of this file.

canUploadVersion

public boolean canUploadVersion(String name)

Checks if a new version of the file can be uploaded with the specified name.

Parameters:

name - the new name for the file.

Returns:

whether or not the file version can be uploaded.

canUploadVersion

public boolean canUploadVersion(String name,
                                long fileSize)

Checks if a new version of the file can be uploaded with the specified name and size.

Parameters:

name - the new name for the file.

fileSize - the size of the new version content in bytes.

Returns:

whether the file version can be uploaded.

uploadNewVersion

public BoxFile.Info uploadNewVersion(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.

Returns:

the uploaded file version.

uploadNewVersion

public BoxFile.Info uploadNewVersion(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.

Returns:

the uploaded file version.

uploadNewVersion

public BoxFile.Info uploadNewVersion(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.

Returns:

the uploaded file version.

uploadNewVersion

public BoxFile.Info uploadNewVersion(InputStream fileContent,
                                     String fileContentSHA1,
                                     Date modified,
                                     String name)

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.

name - the new name for the file

Returns:

the uploaded file version.

uploadNewVersion

public BoxFile.Info uploadNewVersion(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.

Returns:

the uploaded file version.

uploadNewVersion

public BoxFile.Info uploadNewVersion(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.

Returns:

the uploaded file version.

uploadNewVersion

public BoxFile.Info uploadNewVersion(InputStream fileContent,
                                     String fileContentSHA1,
                                     Date modified,
                                     String name,
                                     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.

name - the new name for the file

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

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

Returns:

the uploaded file version.

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

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

Gets a list of any tasks on this file with requested fields.

Parameters:

fields - optional fields to retrieve for this task.

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.

setMetadata

public Metadata setMetadata(String templateName,
                            String scope,
                            Metadata metadata)

Sets the provided metadata on the file. If metadata has already been created on this file, it overwrites metadata keys specified in the `metadata` param.

Parameters:

templateName - the name of the metadata template.

scope - the scope of the template (usually "global" or "enterprise").

metadata - the new metadata values.

Returns:

the metadata returned from the server.

addClassification

public String addClassification(String classificationType)

Adds a metadata classification to the specified file.

Parameters:

classificationType - the metadata classification type.

Returns:

the metadata classification type added to the file.

updateClassification

public String updateClassification(String classificationType)

Updates a metadata classification on the specified file.

Parameters:

classificationType - the metadata classification type.

Returns:

the new metadata classification type updated on the file.

setClassification

public String setClassification(String classificationType)

Attempts to add classification to a file. If classification already exists then do update.

Parameters:

classificationType - the metadata classification type.

Returns:

the metadata classification type on the file.

getClassification

public String getClassification()

Gets the classification type for the specified file.

Returns:

the metadata classification type on the file.

deleteClassification

public void deleteClassification()

Deletes the classification on the file.

lock

public BoxLock lock()

Locks a file.

Returns:

the lock returned from the server.

lock

public BoxLock lock(boolean isDownloadPrevented)

Locks a file.

Parameters:

isDownloadPrevented - is downloading of file prevented when locked.

Returns:

the lock 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,
                                    Map<String,String> fileAttributes)
                             throws InterruptedException,
                                    IOException

Creates a new version of a file. Also sets file attributes.

Parameters:

inputStream - the stream instance that contains the data.

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

fileAttributes - file attributes to set

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.

uploadLargeFile

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

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

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

fileAttributes - file attributes to set

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,
                                         Date expiresAt,
                                         Boolean isAccessOnly)

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.

expiresAt - when the collaboration should expire.

isAccessOnly - whether the collaboration is access only or not.

Returns:

info about the new collaboration.

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,
                                         Date expiresAt,
                                         Boolean isAccessOnly)

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.

expiresAt - when the collaboration should expire.

isAccessOnly - whether the collaboration is access only 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.