Skip to content

Latest commit

 

History

History
1096 lines (855 loc) · 45.6 KB

files.md

File metadata and controls

1096 lines (855 loc) · 45.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... fields) 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 object or updating an existing one, and then calling updateInfo(BoxFile.Info fieldsToUpdate).

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 stream) 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 stream, ProgressListener progress). 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 fileContents, String fileName) method on the BoxFolder you want to upload the file into.

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

Note that using FileInputStream allows you to read the content of the file only once. If the first upload attempt fails, the stream will become exhausted, and request retry with no content might be performed. To retry an upload, you would have to create a new FileInputStream and call uploadFile() method again.

If you want the SDK to automatically retry the upload in case of any error, you need to provide an InputStream class that supports the reset() operation. For example, you can read all bytes from your file into a ByteArrayInputStream and then use it for the upload method. Be aware that this approach will load the whole file into memory, so it is not recommended for large files, as it can exhaust easily your memory.

BoxFolder rootFolder = BoxFolder.getRootFolder(api);
InputStream stream = new ByteArrayInputStream(Files.readAllBytes(new File(path).toPath()));
BoxFile.Info newFileInfo = 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 fileContents, String fileName, long fileSize, ProgressListener progress). The ProgressListener will then receive progress updates as the upload completes.

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

We also support the ability to attach a description of the file upon upload by calling the uploadFile(InputStream fileContents, String fileName, String fileDescription) method.

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

Upload Preflight Check

You may want to check if a file can be successfully uploaded before beginning the file transfer, in order to the time and bandwidth of sending the file over the network if the upload would not have succeeded. Calling the BoxFolder#canUpload(String fileName, long fileSize) method on the folder you want to upload a new file into will verify that there is no name conflict and that the account has enough storage space for the file.

String fileName = "My Doc.pdf";
BoxFolder rootFolder = BoxFolder.getRootFolder(api);
try {
    folder.canUpload(fileName, 98734576);

    // If the file upload would not have succeeded, it will not be attempted
    folder.uploadFile(fileContents, fileName);
} catch (BoxAPIException ex) (

)

Upload a Large File in Chunks

A large file can be uploaded with the uploadLargeFile(InputStream fileContents, String fileName, long fileSize) method on the folder to upload the new file into. This will upload the file in parts with integrity checks on each part, to ensure that network errors mid-upload do not fail the entire operation.

File myFile = new File("My Large_File.txt"); 
FileInputStream stream = new FileInputStream(myFile);

BoxFolder rootFolder = BoxFolder.getRootFolder(api);
BoxFile.Info fileInfo = rootFolder.uploadLargeFile(inputStream, "My_Large_File.txt", myFile.length());

Upload a Large File in Chunks Including Attributes

A large file can be uploaded, including attributes, with the uploadLargeFile(InputStream fileContents, String fileName, long fileSize, Map<String, String> fileAttributes) method on the folder to upload the new file into. This will upload the file in parts with integrity checks on each part, to ensure that network errors mid-upload do not fail the entire operation.

File myFile = new File("My Large_File.txt"); 
FileInputStream stream = new FileInputStream(myFile);
Map<String, String> fileAttributes = new HashMap<String, String>();
fileAttributes.put("content_modified_at", "2017-04-08T00:58:08Z");

BoxFolder rootFolder = BoxFolder.getRootFolder(api);
BoxFile.Info fileInfo = rootFolder.uploadLargeFile(inputStream, "My_Large_File.txt", myFile.length(), fileAttributes);

Upload a Large File Version in Chunks

To upload a new file version for a large file, call the uploadLargeFile(InputStream fileContents, long fileSize) method on the file to be updated. This will upload the new version of the file in parts with integrity checks on each part, to ensure that network errors mid-upload do not fail the entire operation.

File myFile = new File("My Large_File.txt"); 
FileInputStream stream = new FileInputStream(myFile);

String fileID = "12345";
BoxFile file = new BoxFile(api, fileID);
BoxFile.Info fileInfo = file.uploadLargeFile(inputStream, myFile.length());

Upload a Large File Version in Chunks Including Attributes

To upload a new file version for a large file, including attributes, call the uploadLargeFile(InputStream fileContents, long fileSize, Map<String, String> fileAttributes) method on the file to be updated. This will upload the new version of the file in parts with integrity checks on each part, to ensure that network errors mid-upload do not fail the entire operation.

File myFile = new File("My Large_File.txt"); 
FileInputStream stream = new FileInputStream(myFile);
Map<String, String> fileAttributes = new HashMap<String, String>();
fileAttributes.put("content_modified_at", "2017-04-08T00:58:08Z");

String fileID = "12345";
BoxFile file = new BoxFile(api, fileID);
BoxFile.Info fileInfo = file.uploadLargeFile(inputStream, myFile.length(), fileAttributes);

Upload a Large File Or File Version Manually

To start the process of uploading a large file or file version, first create a new upload session with BoxFolder#createUploadSession(String fileName, String fileSize) for a new file, or BoxFile#createUploadSession(long fileSize) for a new file version. Once the upload session is created, all other steps are identical for both cases.

BoxFileUploadSession.Info sessionInfo;
if (/* uploading a new file */) {
    // Create the upload session for a new file
    BoxFolder rootFolder = BoxFolder.getRootFolder(api);
    sessionInfo = rootFolder.createUploadSession("New Large File.pdf", fileSize);
} else if (/* uploading a new version of an exiting file */) {
    // Create the uplaod session for a new version of an existing file
    String fileID = "93465";
    BoxFile file = new BoxFile(api, fileID);
    sessionInfo = file.createUploadSession(fileSize);
}

//Get the session resource from the session info
BoxFileUploadSession session = sessionInfo.getResource();

//Create the Message Digest for the whole file
MessageDigest digest = null;
try {
    digest = MessageDigest.getInstance("SHA1");
} catch (NoSuchAlgorithmException ae) {
    throw new BoxAPIException("Digest algorithm not found", ae);
}

Both of these methods will return a

Once the upload session is created, the large file can be uploaded in chunks with the uploadPart(InputStream stream, long offset, int partSize, long totalSizeOfFile) method of the session instance. If there is a failure in uploading any of the parts, the failed part can be uploaded again without affecting the other parts.

//Reading a large file
FileInputStream fis = new FileInputStream("My_Large_File.txt");
//Create the digest input stream to calculate the digest for the whole file.
DigestInputStream dis = new DigestInputStream(fis, digest);

List<BoxFileUploadSessionPart> parts = new ArrayList<BoxFileUploadSessionPart>();

//Get the part size. Each uploaded part should match the part size returned as part of the upload session.
//The last part of the file can be less than part size if the remaining bytes of the last part is less than
//the given part size
long partSize = sessionInfo.getPartSize();
//Start byte of the part
long offset = 0;
//Overall of bytes processed so far
long processed = 0;
while (processed < fileSize) {
    long diff = fileSize - processed;
    //The size last part of the file can be less than the part size.
    if (diff < partSize) {
        partSize = diff;
    }

    //Upload a part. It can be uploaded asynchorously
    BoxFileUploadSessionPart part = session.uploadPart(dis, offset, (int)partSize, fileSize);
    parts.add(part);

    //Increase the offset and proceesed bytes to calculate the Content-Range header.
    processed += partSize;
    offset += partSize;
}

At any point in time, the list of parts that have been uploaded successfully can be retrieved with the listParts(int offset, int limit) method of the session instance.

//The following snippet retrives first 1000 parts that are uploaded.
BoxFileUploadSessionPartList partList = session.listParts(0, 1000);
List<BoxFileUploadSessionPart> parts = partList.getEntries();

Once all the parts are uploaded successfully, the upload session can be committed with the commit(String digest, List<BoxFileUploadSessionPart> parts, Map<String, String> attributes, String ifMatch, String ifNoneMatch) method.

//Creates the file hash
byte[] digestBytes = digest.digest();
//Base64 encoding of the hash
String digestStr = Base64.encode(digestBytes);

//Commit the upload session. If there is a failure, abort the commit.
BoxFile.Info fileInfo = session.commit(digestStr, parts, null, null, null);

The upload session can be aborted at any time with the abort() method of the session instance. This will cancel the upload and any parts that were already uploaded will be lost.

session.abort();

The upload session status can be retrieved at any time with the getStatus() method. This call will update the parts processed and other information in the session info instance.

BoxFileUploadSession.Info updatedSessionInfo = session.getStatus();

Move a File

To move a file from one folder into another, call move(BoxFolder destination) on the file to be moved with the destination folder.

String fileID = "1234";
String destinationFolderID = "5678";
BoxFile file = new BoxFile(api, fileID);
BoxFolder destinationFolder = new BoxFolder(destinationFolderID);
file.move(destinationFolder)

To avoid name conflicts in the destination folder, you can optionally provide a new name for the file to move(BoxFolder destination, String newName). The file will be placed into the destination folder with the new name.

String fileID = "1234";
String destinationFolderID = "5678";
BoxFile file = new BoxFile(api, fileID);
BoxFolder destinationFolder = new BoxFolder(destinationFolderID);
file.move(destinationFolder, "Vacation Photo (1).jpg");

Copy a File

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

// Copy a file into the user's root folder
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. By default, it will return up to 1000 file versions with all default fields set.

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

File versions can be retrieved with specified starting position with the [getVersionsRange(long offset, long limit)][get-versions-range] method. You can use the limit and offset parameters to page through the all available file versions.

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

You can specify selected fields to be returned while getting versions information. Assume we want to get version SHA1 and version number:

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

You can find a list of available fields at BoxFile.ALL_VERSION_FIELDS.

Upload a New Version of a File

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

BoxFile file = new BoxFile(api, "id");
FileInputStream stream = new FileInputStream("My File.txt");
file.uploadNewVersion(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 output).

BoxFile file = new BoxFile(api, "id");
Collection<BoxFileVersion> versions = file.getVersions();
BoxFileVersion firstVersion = versions.iterator().next();

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");
Collection<BoxFileVersion> versions = file.getVersions();
BoxFileVersion firstVersion = versions.iterator().next();
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");
Collection<BoxFileVersion> versions = file.getVersions();
BoxFileVersion firstVersion = versions.iterator().next();
firstVersion.delete();

Lock a File

A file can be locked indefinitely by calling lock() on the file to be locked. A locked file cannot be modified by any other user until it is unlocked. This is useful if you want to "check out" a file while you're working on it, to ensure that other collaborators do not make changes while your changes are in progress.

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

When locking a file, you can optionally prevent other users from downloading the file in addition to prevent changes by calling lock(boolean preventDownload) with true.

// Lock the file and prevent downloading
BoxFile file = new BoxFile(api, "id");
file.lock(true);

You can also set a date when the lock will automatically be released by calling lock(Date expirationDate) with the date on which the lock should expire. This is recommended to prevent a file from accidentally being locked longer than intended.

final long ONE_WEEK_MILLIS = 1000 * 60 * 60 * 24 * 7;
long expirationTimestamp = System.currentTimeMillis() + ONE_WEEK_MILLIS;
Date expirationTime = new Date(expirationTimestamp);
BoxFile file = new BoxFile(api, "id");
file.lock(expirationTime);

Both options can be passed together to lock(boolean preventDownload, Date expireTime).

Unlock a File

A file can be unlocked by calling unlock().

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

Find File for Shared Link

To get the file information for a shared link, you can call BoxItem.getSharedItem(BoxAPIConnection api, String sharedLink) with the shared link to get information about the file behind it.

String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456";
BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink);

If the shared link is password-protected, call BoxItem.getSharedItem(BoxAPIConnection api, String sharedLink, String password) with the shared link and password.

String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456";
String password = "letmein";
BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink, password);

Create a Shared Link

A shared link for a file can be generated by calling createSharedLink(BoxSharedLinkRequest sharedLinkRequest).

// Optionally we can calculate and set the date when shared link will automatically be disabled
final long ONE_WEEK_MILLIS = 1000 * 60 * 60 * 24 * 7;
long unsharedTimestamp = System.currentTimeMillis() + ONE_WEEK_MILLIS;
Date unsharedDate = new Date(unsharedTimestamp);

BoxFile file = new BoxFile(api, "id");
BoxSharedLinkRequest sharedLinkRequest = new BoxSharedLinkRequest()
    .access(OPEN)
    .permissions(true, true)
    .unsharedDate(unsharedDate);
BoxSharedLink sharedLink = file.createSharedLink(sharedLinkRequest);

A set of shared link access level constants are available through the SDK for convenience:

  • BoxSharedLink.Access.OPEN
  • BoxSharedLink.Access.COLLABORATORS
  • BoxSharedLink.Access.COMPANY
  • BoxSharedLink.Access.DEFAULT

Get a Shared Link

Retrieve the shared link for a file by calling getSharedLink().

BoxFile file = new BoxFile(api, "id");
BoxFile.Info info = file.getInfo()
BoxSharedLink link = info.getSharedLink()
String url = link.getUrl()

Update a Shared Link

A shared link for a file can be updated by calling the same method as used when creating a shared link, createSharedLink(BoxSharedLinkRequest sharedLinkRequest).

BoxFile file = new BoxFile(api, "id");
BoxSharedLinkRequest sharedLinkRequest = new BoxSharedLinkRequest()
    .access(OPEN)
    .permissions(true, true);
BoxSharedLink sharedLink = file.createSharedLink(sharedLinkRequest);

Remove a Shared Link

A shared link for a file can be removed by calling removeSharedLink().

BoxFile file = new BoxFile(api, "12345");
BoxFile.Info info = file.getInfo();
info.removeSharedLink();
file.updateInfo(info);

Add a Collaborator

You can invite another person to collaborate on a file by email with collaborate(String emailAddress, BoxCollaboration.Role role, Boolean notify, Boolean canViewPath, Date expiresAt, Boolean isAccessOnly).

The notify parameter will determine if the user or group will receive an email notification when being added as a collaborator. This option is only available to enterprise administrators.

The canViewPath parameter allows the invitee to see the entire list of ancestor folders of the associated file. The user will not gain privileges in any ancestor folder, but will be able to see the whole path to that file in the owner's account.

The expiresAt parameter allows the owner to set a date-time in the future when the collaboration should expire.

The isAccessOnly parameter allows the owner to set the collaboration to be access only collaboration.

The notify, canViewPath, expiresAt and isAccessOnly parameters can be left as null.

BoxFile file = new BoxFile(api, "id");
BoxCollaboration.Info collabInfo = file.collaborate("[email protected]", BoxCollaboration.Role.EDITOR, true, true);

Alternatively, if you know the user's ID, you can invite them directly without needing to know their email address with the collaborate(BoxCollaborator user, BoxCollaboration.Role role, Boolean notify, Boolean canViewPath, Date expiresAt, Boolean isAccessOnly)

BoxUser collaborator = new BoxUser(api, "user-id");
BoxFile file = new BoxFile(api, "file-id");
BoxCollaboration.Info collabInfo = file.collaborate(collaborator, BoxCollaboration.Role.EDITOR, true, true);

Get an Embed Link

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

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

Create Metadata

Metadata can be created on a file by calling createMetadata(Metadata metadata), createMetadata(String typeName, Metadata metadata), or createMetadata(String typeName, String scope, Metadata metadata).

// Add property "foo" with value "bar" to the default metadata properties
BoxFile file = new BoxFile(api, "id");
file.createMetadata(new Metadata().add("/foo", "bar"));

Note: This method will only succeed if the provided metadata template is not currently applied to the file, otherwise it will fail with a Conflict error. To get to know how to edit existing metadata please go to set metadata and update metadata sections.

Set Metadata

To set metadata on a file, call setMetadata(String templateName, String scope, Metadata metadata). This method will try to create provided metadata on a file. However, if metadata has already been applied to this file, it will overwrite values of metadata keys specified in the metadata parameter. The metadata keys not specified in the metadata parameter will remain unchanged.

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

Note: If you want to set new metadata on a file including hard reset of the current metadata (also removing keys not specified in the metadata param): first delete metadata as specified in delete metadata section and then set new metadata again.

Get Metadata

Retrieve a file's Metadata by calling getMetadata(), getMetadata(String typeName), or getMetadata(String typeName, String scope). These methods return a Metadata object, which allows access to metadata values.

// Get the default free-form metadata properties
BoxFile file = new BoxFile(api, "id");
Metadata metadata = file.getMetadata();

// Unknown type metadata field, you can test for type or try to get as any type
JsonValue unknownValue = metadata.getValue("/someField");

// String or Enum metadata fields
String stringValue = metadata.getString("/author");

// Float metadata fields can be interpreted as any numeric type
float floatValue = metadata.getFloat("/price");

// Date metadata fields
Date dateValue = metadata.getDate("/deadline");

// Multiselect metadata fields
List<String> multiSelectValues = metadata.getMultiSelect("/categories");

Update Metadata

Update a file's Metadata by calling updateMetadata(Metadata properties).

Note: This method will only succeed if the provided metadata template has already been applied to the file. If the file does not have existing metadata, this method will fail with a Not Found error. This is useful in cases where you know the file will already have metadata applied, since it will save an API call compared to setMetadata().

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

Also, it is possible to add multi-select fields for your file metadata by calling updateMetadata(Metadata properties) with a list of values.

BoxFile file = new BoxFile(api, "id");
List<String> valueList = new ArrayList<String>();
valueList.add("bar");
valueList.add("qux");
file.updateMetadata(new Metadata("templateScope", "templateKey").add("/foo", valueList));

If you wanted to replace all selected fields for a specified key you can use the replace(String path, List<String> values).

BoxFile file = new BoxFile(api, "id");
List<String> valueList = new ArrayList<String>();
valueList.add("bar");
valueList.add("qux");
file.updateMetadata(new Metadata("templateScope", "templateKey").replace("/foo", valueList));

If you wanted to remove a metadata value for a specified key you can use the remove(String path).

BoxFile file = new BoxFile(api, "id");
file.updateMetadata(new Metadata("templateScope", "templateKey").remove("/foo"));

Delete Metadata

A file's Metadata can be deleted by calling deleteMetadata(), deleteMetadata(String typeName), or deleteMetadata(String typeName, String scope).

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

Get All Metadata on File

Calling the getAllMetadata() method on a file will return an iterable that will page through all of the metadata associated with the file.

BoxFile file = new BoxFile(api, "id");
Iterable<Metadata> metadataList = file.getAllMetadata();
for (Metadata metadata : metadataList) {
    // Do something with the metadata.
}

Set Classification on File

Calling the setClassification(String classificationType) method on a file will add a classification template on the file. This method will return the classification type applied on the file. The classification types include Public, Internal, and Confidential. Public being the most available permission, Internal which restricts the specified file to company and collaborators only, and finally, Confidential, which is for collaborators only.

BoxFile file = new BoxFile(api, "id");
String classificationType = file.setClassification("Public");

It is important to note that this call will attempt to create a classification on the file first, if one already exists then it will do the update. If you already know that a classification exists on the file and would like to save an API call, we encourage you to use the updateClassification(String classificationType) method.

BoxFile file = new BoxFile(api, "id");
String classificationType = file.updateClassification("Public");

Get Classification on File

To retrieve the classification assigned on the file, use the getClassification() method. This will return the classification type on the file.

BoxFile file = new BoxFile(api, "id");
String classificationType = file.getClassification();

Remove Classification on File

To remove classification from the file, use the deleteClassification() method.

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

Get File Representations

To get the preview representations of a file, call the getInfoWithRepresentations(String representationHints, String... fields) method with the representation hints to fetch, along with any other fields on the file object to fetch simultaneously. This method returns a BoxFile.Info object that contains the representations as a list of Representation objects.

Note that this method only provides information about a set of available representations; your application will need to handle checking the status of the representations and downlaoding them via the provided content URL template.

BoxFile file = new BoxFile(api, "1234");

// Get the PDF representation and file name
String repHints = "[pdf]";
BoxFile.Info fileInfo = file.getInfoWithRepresentations(repHints, "name");
List<Representation> representations = fileInfo.getRepresentations();
String name = fileInfo.getName();

Get Representation Content

To write the contents of a single file representation to an OutputStream, call the getRepresentationContent(String representationHint, OutputStream output) method with an X-Rep-Hints value specifying the representation you want.

Note: This method only supports getting the contents of a single representation; if your X-Rep-Hints value specifies multiple representations, an arbitrary one of them will be fetched.

// Read the PDF representation of file 12345 into memory
ByteArrayOutputStream output = new ByteArrayOutputStream();

BoxFile file = new BoxFile(api, "12345");
file.getRepresentationContent("[pdf]", output);

For representations with multiple files, e.g. multi-page images, you will need to pass an assetPath parameter to specify which file you want to fetch.

// If file 12345 is a document, its PNG representation will consist of one image per page of the document
// Get the image of the first page of the document and write it to a file
FileOutputStream output = new FileOutputStream("/path/to/file.png");
BoxFile file = new BoxFile(api, "12345");
file.getRepresentationContent("[png?dimensions=1024x1024]", "1.png", output);

Generating a representation for the selected file is an asynchronous operation and may take some time. Therefore, by default, the getRepresentationContent method periodically checks the status of the generated file and downloads it when it is ready. With the maxRetries parameter in getRepresentationContent(String representationHint, String assetPath, OutputStream output, int maxRetries), you can define the number of status checks for the generated file, which will be performed at intervals of 100 ms.

If this number is exceeded, a BoxApiException will be thrown.

FileOutputStream output = new FileOutputStream("/path/to/file.png");
BoxFile file = new BoxFile(api, "12345");
file.getRepresentationContent("[png?dimensions=1024x1024]", "1.png", output, 10);