files.md

Files

File objects represent individual files in Box. They can be used to download a file's contents, upload new versions, and perform other common file operations (move, copy, delete, etc.).

• Get a File's Information
• Update a File's Information
• Download a File
• Upload a File
• Copy a File
• Delete a File
• Get Previous Versions of a File
• Upload a New Version of a File
• Download a Previous Version of a File
• Promote a Previous Version of a File
• Delete a Previous Version of a File

Get a File's Information

Calling getInfo() on a file returns a snapshot of the file's info.

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

Requesting information for only the fields you need with [getInfo(String...)] get-info2 can improve performance and reduce the size of the network request.

BoxFile file = new BoxFile(api, "id");
// Only get information about a few specific fields.
BoxFile.Info info = file.getInfo("size", "owned_by");

Update a File's Information

Updating a file's information is done by creating a new [BoxFile.Info] box-file-info object or updating an existing one, and then calling updateInfo(BoxFile.Info).

BoxFile file = new BoxFile(api, "id");
BoxFile.Info info = file.new Info();
info.setName("New Name");
file.updateInfo(info);

Download a File

A file can be downloaded by calling download(OutputStream) and providing an OutputStream where the file's contents will be written.

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

FileOutputStream stream = new FileOutputStream(info.getName());
file.download(stream);
stream.close();

Download progress can be tracked by providing a ProgressListener to download(OutputStream, ProgressListener). The ProgressListener will then receive progress updates as the download completes.

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

FileOutputStream stream = new FileOutputStream(info.getName());
// Provide a ProgressListener to monitor the progress of the download.
file.download(stream, new ProgressListener() {
    public void onProgressChanged(long numBytes, long totalBytes) {
        double percentComplete = numBytes / totalBytes;
    }
});
stream.close();

Upload a File

Files are uploaded to a folder by calling the uploadFile(InputStream, String) method.

BoxFolder rootFolder = BoxFolder.getRootFolder(api);
FileInputStream stream = new FileInputStream("My File.txt");
rootFolder.uploadFile(stream, "My File.txt");
stream.close();

Upload progress can be tracked by providing the size of the file and a ProgressListener to uploadFile(InputStream, String, long, ProgressListener). The ProgressListener will then receive progress updates as the upload completes.

BoxFolder rootFolder = BoxFolder.getRootFolder(api);
FileInputStream stream = new FileInputStream("My File.txt");
rootFolder.uploadFile(stream, "My File.txt", 1024, new ProgressListener() {
    public void onProgressChanged(long numBytes, long totalBytes) {
        double percentComplete = numBytes / totalBytes;
    }
});
stream.close();

Copy a File

A file can be copied to a new folder and optionally be renamed with the copy(BoxFolder) and copy(BoxFolder, String) methods.

BoxFolder rootFolder = BoxFolder.getRootFolder(api);
BoxFile file = new BoxFile(api, "id");
BoxFile.Info copiedFileInfo = file.copy(rootFolder, "New Name");

Delete a File

Calling the delete() method will move the file to the user's trash.

BoxFile file = new BoxFile(api, "id");
file.delete();

Get Previous Versions of a File

For users with premium accounts, versions of a file can be retrieved with the getVersions() method.

BoxFile file = new BoxFile(api, "id");
List<BoxFileVersion> versions = file.getVersions();
for (BoxFileVersion version : versions) {
    System.out.format("SHA1 of \"%s\": %s\n", item.getName(), version.getSha1());
}

Upload a New Version of a File

New versions of a file can be uploaded with the uploadVersion(InputStream) method.

BoxFile file = new BoxFile(api, "id");
FileInputStream stream = new FileInputStream("My File.txt");
file.uploadVersion(stream);

Download a Previous Version of a File

For users with premium accounts, previous versions of a file can be downloaded by calling download(OutputStream).

BoxFile file = new BoxFile(api, "id");
List<BoxFileVersion> versions = file.getVersions();
BoxFileVersion firstVersion = versions.get(0);

FileOutputStream stream = new FileOutputStream(firstVersion.getName());
firstVersion.download(stream);
stream.close();

Promote a Previous Version of a File

A previous version of a file can be promoted with the promote() method to become the current version of the file.

BoxFile file = new BoxFile(api, "id");
List<BoxFileVersion> versions = file.getVersions();
BoxFileVersion firstVersion = versions.get(0);
firstVersion.promote();

Delete a Previous Version of a File

A version of a file can be deleted and moved to the trash by calling delete().

BoxFile file = new BoxFile(api, "id");
List<BoxFileVersion> versions = file.getVersions();
BoxFileVersion firstVersion = versions.get(0);
firstVersion.delete();