Skip to content

Latest commit

 

History

History
359 lines (267 loc) · 12.6 KB

files.md

File metadata and controls

359 lines (267 loc) · 12.6 KB
Raw

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

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

Lock a File

A file can be locked by calling lock(Date).

BoxFile file = new BoxFile(api, "id");
Date expiresAt = new Date();
file.lock(expiresAt);

Unlock a File

A file can be unlocked by calling unlock().

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

Create a Shared Link

A shared link for a file can be generated by calling createSharedLink(BoxSharedLink.Access, Date, BoxSharedLink.Permissions).

BoxFile file = new BoxFile(api, "id");
BoxSharedLink.Permissions permissions = new BoxSharedLink.Permissions();
permissions.setCanDownload(true);
permissions.setCanPreview(true);
Date unshareDate = new Date();
BoxSharedLink sharedLink = file.createSharedLink(BoxSharedLink.Access.OPEN, unshareDate, permissions);

Get an Embed Link

A file embed link can be generated by calling getPreviewLink().

BoxFile file = new BoxFile(api, "id");
URL embedLink = file.getPreviewLink();

Get Thumbnail

A thumbnail for a file can be retrieved by calling getThumbnail(BoxFile.ThumbnailFileType, int, int, int).

BoxFile file = new BoxFile(api, "id");
byte[] thumbnail = file.getThumbnail(BoxFile.ThumbnailFileType.PNG, 256, 256, 256, 256)

Create Metadata

Metadata can be created on a file by calling createMetadata(Metadata), createMetadata(String, Metadata), or createMetadata(String, String, Metadata)

BoxFile file = new BoxFile(api, "id");
file.createMetadata(new Metadata().add("/foo", "bar"));

Get Metadata

Retrieve a files Metadata by calling getMetadata(), getMetadata(String), or getMetadata(String, String).

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

Update Metadata

Update a files Metadata by calling updateMetadata(Metadata).

BoxFile file = new BoxFile(api, "id");
file.updateMetadata(new Metadata().add("/foo", "bar"));

Delete Metadata

A files Metadata can be deleted by calling deleteMetadata(), deleteMetadata(String), or deleteMetadata(String, String).

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