Skip to content

Latest commit

 

History

History
388 lines (293 loc) · 13.9 KB

folders.md

File metadata and controls

388 lines (293 loc) · 13.9 KB
Raw

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

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

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

Created a Shared Link for a Folder

You can get a shared link for a folder by calling the createSharedLink(BoxSharedLink.Access accessLevel, Date expirationDate, BoxSharedLink.Permissions permissions) method.

BoxFolder folder = new BoxFolder(api, "id");
SharedLink link = folder.createSharedLink(BoxSharedLink.Access.OPEN, null,
    permissions);

A shared link can also be created 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.

BoxSharedLink sharedLink = new BoxSharedLink();
sharedLink.setAccess(BoxSharedLink.Access.OPEN);

BoxFolder folder = new BoxFolder(api, "id");
BoxFolder.Info info = folder.new Info();
info.setSharedLink(sharedLink);
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("[email protected]",
    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();

Create Metadata

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)

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

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

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) {
    Metadata itemMetadata = itemInfo.getMetadata("properties", "global");
}