한국어 (korean) | English

OneDrive API for Java

purse fast, easy to use, intuitive API.

Supported Operation

• Auto login authorization check and refresh
• Fetching metadata of folder, file (by id and path)
• Folder or file's metadata (size, name, path, children list and etc.)
• Downloading file (sync and async)
• Delete, copy, move, change metadata(name, description) of folder or file
• Creating folder
• Resources that OneDrive support like image, video..
• Inquiring shared folder
• Basic RemoteItem handling
• Inquiring Drives
• Creating file and upload it (async)
• Support Microsoft Graph 1.0
• Support OneDrive for Business (not fully tested)

TODO

• Searching file or folder (by name or content)
• Sharing folder or file
• Documentation
• Support custom redirect url when login
• REST-api response error handling
• JRE6 version
• HTTPS GZIP support for synchronized operation

Environment

• JRE7

Dependency

These are already included in gradle configuration file 'build.gradle'.

• Jackson
• Lombok
• netty

Build

jar files will be located on build/libs after build

Windows

gradlew.bat build

Linux, MacOS

./gradlew build

if gradle is installed in your computer

gradle build

Simple example

You can see little bit more complicated examples in TestCode.java

1. Construct Client object

• All OneDrive jobs are performed via Client object.
• A program can contain multiple different Client object.
• Basically Client object check expiration and refresh authorization automatically. but it can be done manually.
• All parameters that pass to Client's constructor can obtain if you fallow OneDrive app instruction of authentication.

import com.bhyoo.onedrive.client.Client;

String clientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
String[] scope = {"files.readwrite.all", "offline_access"};
String redirectURL = "http://localhost:8080/";
String clientSecret = "xxxxxxxxxxxxxxxxxxxxxxx";

// with login
Client client = new Client(clientId, scope, redirectURL, clientSecret);
// without login
Client client = new Client(clientId, scope, redirectURL, clientSecret, false);
client.login();

// With tokens provided from outside source 
String accessToken = "<access_token>";
String refreshToken = "<refresh_token>"
String tokenType = "bearer";
long expiresIn = 0;

Client client = new Client(clientId, scope, redirectURL, clientSecret, accessToken, refreshToken, tokenType, expiresIn);

2. Folder, file fetch

• It can conduct via either ID or path.
• FolderItem and FileItem are represent folder and file respectively.
• FolderItem and FileItem are child class of DriveItem.

import com.bhyoo.onedrive.container.items.DriveItem;
import com.bhyoo.onedrive.container.items.FileItem;
import com.bhyoo.onedrive.container.items.FolderItem;

// assume that Client object is already constructed

// get root directory
FolderItem root = client.getRootDir();

// get folder by ID
FolderItem folder = client.getFolder("XXXXXXXXXXXXXXXX!XXXX");

// get folder by path
FolderItem folder1 = client.getFolder(new PathPointer("/{item-path}"));

// get file by ID
FileItem file = client.getFile("XXXXXXXXXXXXXXXX!XXXX");

// get file by path
FileItem file1 = client.getFile(new PathPointer("/{item-path}/{file-name}"));

// or if you don't know whether ID is file or folder
DriveItem item = client.getItem("XXXXXXXXXXXXXXXX!XXXX");

// or if you don't know whether path is file or folder
DriveItem item1 = client.getItem(new PathPointer("/{item-path}"));

3. get children of a folder

• FolderItem are Iterable. (it will returns child as DriveItem)
• Basically if FolderItem object is fetched by Client's method getFolder or getRootDir, the object automatically fetchs children too. (If children list is very long, it could take long time)
• If you call FolderItem's method getAllChildren or getFolderChildren or getFileChildren, you can get List of all children, only folder children, only file children respectively.
• if you call above methods, it will load children data and cache it. so First call of those methods can take long time.

import com.bhyoo.onedrive.container.items.DriveItem;
import com.bhyoo.onedrive.container.items.FileItem;
import com.bhyoo.onedrive.container.items.FolderItem;

// assume that Client object is already constructed
FolderItem root = client.getRootDir();

DriveItem[] children = root.allChildren();
FolderItem[] folderChildren = root.folderChildren();
FileItem[] fileChildren = root.fileChildren();

4. Create folder

• It can create via either parent's FolderItem object or Client object.
• It will return created folder's FolderItem object.

import com.bhyoo.onedrive.container.items.FolderItem;
import com.bhyoo.onedrive.container.items.pointer.PathPointer;

// assume that Client object is already constructed

FolderItem root = client.getRootDir();

// create folder by parent folder object
FolderItem newFolder = root.createFolder("test");

// create folder by client with parent folder id
FolderItem newFolder1 = client.createFolder("XXXXXXXXXXXXXXXX!XXXX", "test1");

// create folder by client with parent folder path
FolderItem newFolder2 = client.createFolder(new PathPointer("/"), "test2");

5. Copy folder or file

• It can copy via either source item's object or Client object.

import com.bhyoo.onedrive.container.items.*;
import com.bhyoo.onedrive.container.items.pointer.*;

// assume that Client object is already constructed

FileItem item = (FileItem) client.getItem("XXXXXXXXXXXXXXXX!XXXX");
FolderItem destination = client.getFolder("XXXXXXXXXXXXXXXX!XXXX");

// direct copy
item.copyTo(destination);
// direct copy with new name
item.copyTo(destination, "newName");

// copy by reference object
item.copyTo(destination.newReference());
// copy by reference object with new name
item.copyTo(destination.newReference(), "newName");

// copy by path string
item.copyTo(destination.getPathPointer());
// copy by path string with new name
item.copyTo(destination.getPathPointer(), "newName");

// copy by id string
item.copyTo(destination.getId());
// copy by id string with new name
item.copyTo(destination.getId(), "newName");

// using `Client`, copy by path
client.copyItem(new PathPointer("/{item-path}"), new IdPointer("XXXXXXXXXXXXXXXX!XXXX"));

6. Download file synchronously

import java.nio.file.Paths;
import com.bhyoo.onedrive.container.items.FileItem;

// assume that Client object is already constructed
FileItem file = client.getFile("XXXXXXXXXXXXXXXX!XXXX");

String path = "/home/isac322/download";

// download by system path string with original file name
file.download(path);

// download by system path string with new name
file.download(path, "newName");

// download by path object with original file name
file.download(Paths.get(path));

// download by path object with new name
file.download(Paths.get(path), "newName");

client.download(new PathPointer("/{item-path}"), Paths.get(path));

7. Download file asynchronously

• all async job use Future & Promise mechanism.
• more detail of DownloadFuture will explain later at wiki...

import java.nio.file.Paths;
import com.bhyoo.container.items.FileItem;
import com.bhyoo.network.async.DownloadFuture;

// assume that Client object is already constructed

FileItem file = client.getFile("XXXXXXXXXXXXXXXX!XXXX");
String path = "/home/isac322/download";

// download by path object with original file name
file.downloadAsync(Paths.get(path));

// download by path object with new name
file.downloadAsync(Paths.get(path), "newName");

DownloadFuture future = client.downloadAsync("{file-id}", Paths.get(path), "newName");

// wait until download is done
future.sync();

8. Move folder or file

• It can move via either source item's object or Client object.

import com.bhyoo.onedrive.container.items.FileItem;
import com.bhyoo.onedrive.container.items.FolderItem;
import com.bhyoo.onedrive.container.items.pointer.*;

// assume that Client object is already constructed

FileItem item = client.getFile("XXXXXXXXXXXXXXXX!XXXX");
FolderItem destination = client.getFolder("XXXXXXXXXXXXXXXX!XXXX");

// direct move
item.moveTo(destination);

// move by reference object
item.moveTo(destination.newReference());

// move by path string
item.moveTo(destination.getPathPointer());

// move by id string
item.moveTo(destination.getId());

// using `Client` object, move by folder path
client.moveItem(new PathPointer("/{item-path}"), new IdPointer("XXXXXXXXXXXXXXXX!XXXX"));

9. Update folder or file's metadata & Refresh

• refresh will update all variable with fetched latest metadata.
• That is, if refresh is invoked, all variable can be changed, even if the current program did not modify the variables.

import com.bhyoo.onedrive.container.items.DriveItem;

// assume that Client object is already constructed
DriveItem item = client.getItem("XXXXXXXXXXXXXXXX!XXXX");

// change item's name and flush to server.
item.rename("new name");

// change item's description and flush to server.
item.updateDescription("blah blah");

// refresh item's all variable to latest value
item.refresh();

10. Upload file (asynchronously)

• like asynchronous downloading, it uses Future & Promise mechanism.
• more detail of UploadFuture will explain later at wiki...

import java.nio.file.Path;
import com.bhyoo.onedrive.network.async.UploadFuture;

// assume that Client object is already constructed

UploadFuture future;

// start to upload file
future = client.uploadFile("{remote-folder-id}", Paths.get("local-file-path"));
// wait until uploading is done
future.syncUninterruptibly();

*Item diagram