Skip to content

Latest commit

 

History

History
354 lines (269 loc) · 12.3 KB

folders.md

File metadata and controls

354 lines (269 loc) · 12.3 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) 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 network calls to load more data from Box 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...) 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).

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) 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) 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, String) 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) 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) 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) method. Passing true to this method indicates that the folder and its contents should be recursively deleted.

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, Date, BoxSharedLink.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, BoxCollaboration.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, BoxCollaboration.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), createMetadata(String, Metadata), or createMetadata(String, String, Metadata)

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), or getMetadata(String, String).

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

Update Metadata

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

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), or deleteMetadata(String, String).

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

Get All Metadata on Folder

getAllMetadata(String...) 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("name", "description");
for (Metadata metadata : metadataList) {
    // Do something with the metadata.
}

Get Metadata using unified Metadata API

Metadata actualMD = folder.getInfo("metadata.global.properties").getMetadata("properties", "global");