folders.md

Folders

Folder objects represent a folder from a user's account. They can be used to iterate through a folder's contents, collaborate a folder with another user or group, and perform other common folder operations (move, copy, delete, etc.).

• Get the User's Root Folder
• Get a Folder's Items
• Get a Folder's Information
• Update a Folder's Information
• Create a Folder
• Copy a Folder
• Move a Folder
• Rename a Folder
• Delete a Folder
• Find Folder for Shared Link
• Create a Shared Link
• Get a Shared Link
• Update a Shared Link
• Remove a Shared Link
• Share a Folder
• Get All Collaborations for a Folder
• Set Metadata
• Get Metadata
• Update Metadata
• Delete Metadata
• Get All Metadata on Folder
• Get Metadata for Multiple Files
• Set Classification on Folder
• Get Classification on Folder
• Remove Classification on Folder
• Create Cascade Policy On Folder
• Get a Cascade Policy's Information
• Get All Cascade Policies on Folder
• Force Apply Cascade Policy on Folder
• Delete Cascade Policy
• Lock a Folder
• Get All Locks on a Folder
• Delete A Lock on a Folder

Get the User's Root Folder

The user's root folder can be accessed with the static getRootFolder(BoxAPIConnection api) method.

BoxFolder rootFolder = BoxFolder.getRootFolder(api);

Get a Folder's Items

Every BoxFolder implements Iterable<BoxItem> which allows you to iterate over the folder's contents. The iterator automatically handles paging and will make additional API calls to load more data when necessary.

BoxFolder folder = new BoxFolder(api, "id");
for (BoxItem.Info itemInfo : folder) {
    if (itemInfo instanceof BoxFile.Info) {
        BoxFile.Info fileInfo = (BoxFile.Info) itemInfo;
        // Do something with the file.
    } else if (itemInfo instanceof BoxFolder.Info) {
        BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo;
        // Do something with the folder.
    }
}

BoxFolder purposely doesn't provide a way of getting a collection of BoxItems. Getting the entire contents of a folder is usually unnecessary and can be extremely inefficient for folders with a large number of items. If you really require a collection instead of an iterable, you can create the collection manually.

Collection<BoxItem> folderItems = new ArrayList<BoxItem>();
BoxFolder folder = new BoxFolder(api, "id");
for (BoxItem.Info itemInfo : folder) {
    folderItems.add(itemInfo.getResource());
}

We also allow users to sort the results of the folder items by name, id, or date. This will maintain the integrity of the ordering when you retrieve the items for a folder. You can do this by calling the getChildren(String sortField, BoxFolder.SortDirection sortDirection, String... fields) method.

BoxFolder folder = new BoxFolder(this.api, "12345");
Iterator<BoxItem.Info> itemIterator = folder.getChildren("name", BoxFolder.SortDirection.ASC).iterator();
while (itemIterator.hasNext()) {
    BoxItem.Info itemInfo = itemIterator.next();
    // Do something
}

Get a Folder's Information

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

BoxFolder folder = new BoxFolder(api, "id");
BoxFolder.Info info = folder.getInfo();

Requesting information for only the fields you need can improve performance and reduce the size of the network request. The getInfo(String... fields) method lets you specify which fields are retrieved.

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

Update a Folder's Information

Updating a folder's information is done by creating a new BoxFolder.Info object or updating an existing one, and then calling updateInfo(BoxFolder.Info fieldsToUpdate).

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

Create a Folder

Create a child folder by calling createFolder(String folderName) on the parent folder.

BoxFolder parentFolder = new BoxFolder(api, "id");
BoxFolder.Info childFolderInfo = parentFolder.createFolder("Child Folder Name");

Copy a Folder

Call the copy(BoxFolder destination) method to copy a folder to another folder.

BoxFolder folder = new BoxFolder(api, "id1");
BoxFolder destination = new BoxFolder(api, "id2");
folder.copy(destination);

You can also use the copy(BoxFolder destination, String newName) method to rename the folder while copying it. This allows you to make a copy of the folder in the same parent folder, but with a different name.

BoxFolder folder = new BoxFolder(api, "id1");
BoxFolder.Info parentFolderInfo = folder.getInfo().getParent();
BoxFolder parentFolder = parentFolderInfo.getResource();
folder.copy(parentFolder, "New Name");

Move a Folder

Call the move(BoxFolder destination) method with the destination you want the folder moved to.

BoxFolder folder = new BoxFolder(api, "id1");
BoxFolder destination = new BoxFolder(api, "id2");
folder.move(destination);

Rename a Folder

Call the rename(String newName) method with a new name for the folder.

BoxFolder folder = new BoxFolder(api, "id");
folder.rename("New Name");

A folder can also be renamed by updating the folder's information. This is useful if you want to perform more than one change to the folder in a single API request.

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

Delete a Folder

A folder can be deleted with the delete(boolean recursive) method. Passing true to this method indicates that the folder and its contents should be recursively deleted.

// Delete the folder and all its contents
BoxFolder folder = new BoxFolder(api, "id");
folder.delete(true);

Find Folder for Shared Link

To get the folder information for a shared link, you can call BoxItem.getSharedItem(BoxAPIConnection api, String sharedLink) with the shared link to get information about the folder 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 folder can be generated by calling createSharedLink(BoxSharedLink.Access accessLevel, Date unshareDate, BoxSharedLink.Permissions permissions).

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

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
• accessLevels.DISABLED

Get a Shared Link

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

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

Update a Shared Link

A shared link for a folder can be updated by calling the same method as used when creating a shared link, createSharedLink(BoxSharedLink.Access accessLevel, Date unshareDate, BoxSharedLink.Permissions permissions).

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

Remove a Shared Link

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

BoxFolder folder = new BoxFolder(api, "12345");
BoxFolder.Info info = folder.getInfo();
info.removeSharedLink();
folder.updateInfo(info);

Share a Folder

You can invite another person to collaborate on a folder with the collaborate(String emailAddress, BoxCollaboration.Role role) method.

BoxFolder folder = new BoxFolder(api, "id");
BoxCollaboration.Info collabInfo = folder.collaborate("gcurtis@box.com",
    BoxCollaboration.Role.EDITOR);

If you already 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) method.

BoxUser collaborator = new User(api, "user-id");
BoxFolder folder = new BoxFolder(api, "folder-id");
BoxCollaboration.Info collabInfo = folder.collaborate(collaborator,
    BoxCollaboration.Role.EDITOR);

Get All Collaborations for a Folder

The getCollaborations() method will return a collection of BoxCollaboration.Info objects for a folder.

BoxFolder folder = new BoxFolder(api, "id");
Collection<BoxCollaboration.Info> collaborations = folder.getCollaborations();

Set Metadata

To set metadata on a folder, call setMetadata(String templateKey, String templateScope, Metadata properties).

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

Note: This method will unconditionally apply the provided metadata, overwriting existing metadata for the keys provided. To specifically create or update metadata, please refer to the createMetadata() and updateMetadata() methods.

Metadata can be created on a folder by calling createMetadata(Metadata properties), createMetadata(String templateKey, Metadata properties), or createMetadata(String templateKey, String templateScope, Metadata properties)

Note: This method will only succeed if the provided metadata template is not currently applied to the folder, otherwise it will fail with a Conflict error.

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

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

Get Metadata

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

BoxFolder folder = new BoxFolder(api, "id");
Metadata metadata = folder.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");

Update Metadata

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

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

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

BoxFolder folder = new BoxFolder(api, "id");
List<String> valueList = new ArrayList<String>();
valueList.add("bar");
valueList.add("qux");
folder.updateMetadata(new Metadata().add("/foo", valueList));

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

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

Delete Metadata

A folder's metadata can be deleted by calling deleteMetadata(), deleteMetadata(String templateKey), or deleteMetadata(String templateKey, String templateScope).

BoxFolder folder = new BoxFolder(api, "id");
folder.deleteMetadata("myMetadataTemplate");

Get All Metadata on Folder

getAllMetadata() method will return an iterable that will page through all of the metadata associated with the folder.

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

Get Metadata for Multiple Files

When fetching a large number of items, for example the items in a folder, it would often be impractical to fetch the metadata for each of those items individually. Instead, you can get the metadata for all of the items in a single API call by requesting the metadata field on those items:

Note: The field name should have the form metadata.<templateScope>.<templateKey>

BoxFolder root = BoxFolder.getRootFolder();
Iterable<BoxItem.Info> itemsInFolder = root.getChildren("metadata.global.properties")
for (BoxItem.Info itemInfo : itemsInFolder) {
    if (itemInfo instanceof BoxFile.Info) {
        BoxFile.Info fileInfo = (BoxFile.Info) itemInfo;
        Metadata itemMetadata = fileInfo.getMetadata("properties", "global");
    } else if (itemInfo instanceof BoxFolder.Info) {
        BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo;
        Metadata itemMetadata = folderInfo.getMetadata("properties", "global");
    }
}

Set Classification on Folder

Calling the setClassification(String classificationType) method on a folder will add a classification template on the folder. This method will return the classification type applied on the folder. 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.

BoxFolder folder = new BoxFolder(api, "id");
String classificationType = folder.setClassification("Public");

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

BoxFolder folder = new BoxFolder(api, "id");
String classificationType = folder.updateClassification("Public");

Get Classification on Folder

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

BoxFolder folder = new BoxFolder(api, "id");
String classificationType = folder.getClassification();

Remove Classification on Folder

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

BoxFolder folder = new BoxFolder(api, "id");
folder.deleteClassification();

Create Cascade Policy On Folder

To set a metadata policy, which applies metadata values on a folder to new items in the folder, call BoxFolder.addMetadataCascadePolicy(String scope, String template).

String scope = "global";
String templateKey = "template";
String folderId = "12345";
BoxFolder folder = new BoxFolder(api, folderId);
BoxMetadataCascadePolicy.Info cascadePolicyInfo = folder.addMetadataCascadePolicy(scope, template);

Get a Cascade Policy's Information

To retrieve information about a specific metadata cascade policy, call getInfo()

String cascadePolicyID = "1234";
BoxMetadataCascadePolicy metadataCascadePolicy = new BoxMetadataCascadePolicy(api, cascadePolicyID);
BoxMetadataCascadePolicy.Info metadataCascadePolicyInfo = metadataCascadePolicy.getInfo();

Get All Cascade Policies on Folder

To get a list of all cascade policies on a folder, which show the metadata templates that are being applied to all items in the folder, call getMetadataCascadePolicies() on that folder.

String folderID = "2222";
BoxFolder folder = new BoxFolder(api, folderID);
Iterable<BoxMetadataCascadePolicy.Info> metadataCascadePolicies = folder.getMetadataCascadePolicies();
for (BoxMetadataCascadePolicy.Info policyInfo : metadataCascadePolicies) {
    // take action on policy here
}

You can also call getMetadataCascadePolicies(String enterpriseID, int limit, String... fields) and set the enterpriseID option to retrieve metadata cascade policies from another enterprise.

String folderID = "2222";
String enterpriseID = "3333";
int limit = 50;
BoxFolder folder = new BoxFolder(api, folderID);
Iterable<BoxMetadataCascadePolicy.Info> metadataCascadePolicies = folder.getMetadataCascadePolicies(enterpriseID, limit);
for (BoxMetadataCascadePolicy.Info policyInfo : metadataCascadePolicies) {
    // take action on policy here
}

Force Apply Cascade Policy on Folder

To force apply a metadata template policy and apply metadata values to all existing items in an affected folder, call forceApply(String conflictResolution) with the conflict resolution method for dealing with items that already have a metadata value that conflicts with the folder. Specifying a resolution value of none will preserve the existing values on items, and specifying overwrite will overwrite values on items in the folder with the metadata value from the folder.

String cascadePolicyID = "e4392a41-7de5-4232-bdf7-15e0d6bba067";
BoxMetadataCascadePolicy policy = new BoxMetadataCascadePolicy(api, cascadePolicyID);
policy.forceApply("none");

Delete Cascade Policy

To remove a cascade policy and stop applying metadata from a folder to items in the folder, call delete().

String cascadePolicyID = "e4392a41-7de5-4232-bdf7-15e0d6bba067";
BoxMetadataCascadePolicy policyToDelete = new BoxMetadataCascadePolicy(api, cascadePolicyID);
policyToDelete.delete();

Lock a Folder

To lock a folder and prevent it from being moved and/or deleted, call lock() on a folder.

BoxFolder folder = new BoxFolder(api, "id");
FolderLock.Info folderLock = folder.lock();

Get All Locks on a Folder

To get all locks on a folder, call getlock() on folder.

BoxFolder folder = new BoxFolder(this.api, "id");
Iterable<BoxFolderLock.Info> locks = folder.getLocks();
for (BoxFolderLock.Info lockInfo : locks) {
    // Do something with each lockInfo here
}

Delete a Lock on a Folder

To delete a lock on a folder, call delete() on a BoxFolderLock object. This cannot be called on a BoxFolder object.

BoxFolderLock folderLock = new BoxFolderLock(this.api, "folderLockID");
folderLock.delete();