BoxFile (Box Java SDK)

Object
- BoxResource
- - BoxItem
  - - BoxFile

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

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

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.

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

Method Summary

All Methods Instance Methods Concrete Methods
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.
`void`	`canUploadVersion(String name, long fileSize, String parentID)` Checks if the file can be successfully uploaded by using the preflight check.
`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.
`Metadata`	`createMetadata(String typeName, Metadata metadata)` Creates the metadata of specified type.
`BoxSharedLink`	`createSharedLink(BoxSharedLink.Access access, Date unshareDate, BoxSharedLink.Permissions permissions)` Creates a new shared link for this item.
`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 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.
`List<BoxComment.Info>`	`getComments()` Gets a list of any comments on this file.
`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.
`Metadata`	`getMetadata()` Gets the file properties metadata.
`Metadata`	`getMetadata(String typeName)` Gets the file metadata of specified 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.
`Collection<BoxFileVersion>`	`getVersions()` Gets any previous versions of this 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`	`rename(String newName)` Renames this 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.
`void`	`uploadVersion(InputStream fileContent)` Uploads a new version of this file, replacing the current version.
`void`	`uploadVersion(InputStream fileContent, Date modified)` 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.

Methods inherited from class BoxItem
getSharedItem, getSharedItem

Methods inherited from class BoxResource
equals, getAPI, getID, 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
  - 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.
  - 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.
  - 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,
                          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.
    
    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.
  - 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()
```
    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.
    
    Parameters:
    
    metadata - The new metadata values.
    
    Returns:
    
    the metadata returned from the server.
  - createMetadata
```
public Metadata createMetadata(String typeName,
                               Metadata metadata)
```
    Creates the metadata of specified type.
    
    Parameters:
    
    typeName - the metadata type name.
    
    metadata - the new metadata values.
    
    Returns:
    
    the metadata returned from the server.
  - 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 type.
    
    Parameters:
    
    typeName - the metadata type name.
    
    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 type.
    
    Parameters:
    
    typeName - the metadata type name.

Class BoxFile

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class BoxItem

Methods inherited from class BoxResource

Methods inherited from class Object

Field Detail

ALL_FIELDS

Constructor Detail

BoxFile

Method Detail

createSharedLink

addComment

addTask

download

download

downloadRange

downloadRange

downloadRange

copy

copy

delete

move

move

rename

getInfo

getInfo

updateInfo

getVersions

canUploadVersion

uploadVersion

uploadVersion

uploadVersion

getPreviewLink

getComments

getTasks

createMetadata

createMetadata

getMetadata

getMetadata

updateMetadata

deleteMetadata

deleteMetadata