pCloud Java SDK

The official pCloud SDK for Java & Android for integrating with pCloud's API.

Requirements

• Java 7.0+
• Android 2.3+ (API9+)

Documentation

• The documentation for the SDK can be found here.
• The pCloud API documentation can be found here.

Getting started

1. Create a pCloud account

• Visit pCloud's website and create an account.

2. Register your pCloud API application

• Login to the pCloud Developer Site

• Create an application in the pCloud App Console Page.
  
  

• Take note of the app key(client ID) of your application once you create it.
  

3. Configure your pCloud API application

• Add a publisher.
• Add a description.
• Add a redirect URI in the Redirect URIs field in your application configuration page.

The SDK expects pcloud-oauth://{your.application.package} custom Uri to be added in the Application configuration page.

• Optionally add an icon that will be displayed to users upon authorization requests.
• Turn on the Allow implicit grant option.
• Save the changes.
  

4. Install the SDK

Java

Grab via Maven:

<dependency>
<groupId>com.pcloud.sdk</groupId>
<artifactId>java-core</artifactId>
<version>1.9.1</version>
<type>pom</type>
</dependency>

or Gradle:

implementation 'com.pcloud.sdk:java-core:1.9.1'

Android

In addition to the functionality provided by the java-core module, Android applications can benefit from platform-specific features. The android module provides a built-in authorization Activity that handles the application authorization requests. For details on usage, refer to the AuthorizationActivity documentation.

Grab via Maven:

<dependency>
<groupId>com.pcloud.sdk</groupId>
<artifactId>android</artifactId>
<version>1.9.1</version>
<type>pom</type>
</dependency>

or Gradle:

implementation 'com.pcloud.sdk:android:1.9.1'

Basics

Creating a Client

ApiClientapiClient = PCloudSdk.newClientBuilder()
.authenticator(Authenticators.newOAuthAuthenticator(<yourOAuthaccesstokenhere>))
// Other configuration...
.create();

• ApiClient instances should be reused as much as possible. Avoid creating multiple instances.
• Existing ApiClient instances can be re-configured by calling ApiClient.newBuilder() and creating a new instance.
• Existing ApiClient instances can be 'killed' by calling ApiClient.shutdown().
• For details on the available configuration options, see here

---

Making API calls

Creating a Call:

Call<RemoteFolder> call = apiClient.listFolder(RemoteFolder.ROOT_FOLDER_ID);

• Creating Call instances does not by itself make any API request, treat the objects as a declaration of intent. See the following sections for more information on how to execute calls.
• For a full list of available API calls, see here.

Executing a Call and obtaining the result on the same thread:

RemoteFolderfolder = call.execute();

• Call.execute() will execute the call on the calling thread, blocking it until a response is delivered, a timeout is reached or an error occurs.
• Call.execute() will throw an IOException on a networking error and ApiError on error returned by pCloud's API.
• Request timeouts can be controlled via the methods in ApiClient.Builder
• Avoid calling Call.execute() from the UI thread, as it can potentially block for an extended period of time. On Android applications targetting API11+ , calling this method from the main thread will cause a NetworkOnMainThreadException.

Executing a Call asynchronously:

call.enqueue(newCallback<RemoteFolder>() {
@OverridepublicvoidonResponse(Call<RemoteFolder> call, RemoteFolderresponse) {
// Successful response
}
@OverridepublicvoidonFailure(Call<RemoteFolder> call, Throwablet) {
// Call failed with an error.
}
});

• Call.enqueue() will return immediately, the actual work will scheduled on another thread.
• Callback.onResponse() will be called on a successful response.
• Callback.onFailure() will be called if an error occurs during the execution of the call.
• By default Callback methods will be called on an arbitrary thread, to control this behavior see ApiClient.Builder.callbackExecutor(Executor)

Reusing Call instances:

• A 'Call' instance should be used only once, that is any further call to Call.execute() or 'Call.enqueue()' after the former have been already called, will lead to a runtime exception.
• Calls can be reused by calling Call.clone() that will create a new, identical object, that can be used to make a new API request.

Call<RemoteFolder> newCall = call.clone();

---

File operations

List folder

// Get direct children.RemoteFolderfolder = apiClient.listFolder(<Thefolderidoftargetfolder>);
// Get direct children and other files recursively. (slower and potentialy memory-intensive).RemoteFolderfolder = apiClient.listFolder(<Thefolderidoftargetfolder>, true);

or

RemoteFolderfolder = ...;
// Update folder and children information.RemoteFolderupdatedFolder = folder.update();
// Update folder and children information, including all child entries.RemoteFolderupdatedFolder = folder.update(true);

Copy File

RemoteFilefile = ...;
RemoteFolderdestinationFolder = ...
// Copy file to folder, will block.RemoteFilecopiedFile = file.copy(destinationFolder);

or

ApiClientapiClient =...;
RemoteFilefile = ...;
RemoteFolderdestinationFolder = ...
//Execute call immediately, call will block;RemoteFilecopiedFile = apiClient.copyFile(file, destinationFolder).execute();
// Execute call asynchronouslyapiClient.copyFile(file, destinationFolder).enqueue(newCallback<RemoteFile>() {
@OverridepublicvoidonResponse(Call<RemoteFile> call, RemoteFilecopiedFile) {
// Successful response
}
@OverridepublicvoidonFailure(Call<RemoteFile> call, Throwablet) {
// Call failed with an error.
}
});

Upload a file

• Uploading a local file to pCloud:

ApiClientapiClient =...;
FilelocalFile = ...;
RemoteFileuploadedFile = apiClient.createFile(
RemoteFolder.ROOT_FOLDER_ID,
localFile.getName(),
DataSource.create(localFile),
newDate(localFile.lastModified())
.execute();

• Uploading a local file to pCloud with progress notifications:

ApiClientapiClient =...;
FilelocalFile = ...;
ProgressListenerlistener = newProgressListener() {
publicvoidonProgress(longdone, longtotal) {
System.out.format("\rUploading... %.1f\n", ((double) done / (double) total) * 100d);
}
};
RemoteFileuploadedFile = apiClient.createFile(
RemoteFolder.ROOT_FOLDER_ID,
localFile.getName(),
DataSource.create(localFile),
newDate(localFile.lastModified(),
listener)
.execute();

Download a file

• Download a remote file to a local folder:

RemoteFileremoteFile = ...;
FilelocalFolder = ...;
FilelocalFile = newFile(localFolder, remoteFile.name());
remoteFile.download(DataSink.create(localFile));

• Download a remote file to a local folder with download progress notifications:

RemoteFileremoteFile = ...;
FilelocalFolder = ...;
FilelocalFile = newFile(localFolder, remoteFile.name());
ProgressListenerlistener = newProgressListener() {
publicvoidonProgress(longdone, longtotal) {
System.out.format("\Downloading... %.1f\n", ((double) done / (double) total) * 100d);
}
};
remoteFile.download(DataSink.create(localFile), listener);

• Download a remote file to an arbitrary destination:

RemoteFileremoteFile = ...;
remoteFile.download(newDataSink() {
@OverridepublicvoidreadAll(BufferedSourcesource) throwsIOException {
// Read bytes from source.source.readByte();
// Read bytes with an InputStream:source.inputStream().read();
}});

Samples

Java

See the code in the sample module or the sample application here. The sample explains briefly:

• ApiClient instantiation and configuration.
• File tree browsing and listing folder contents.
• Copy/move/delete/rename operations on files and folders.
• File uploads.
• File downloads.
• File download link generation.

Android

• See the code in the sample-android module or the sample application here.
• The sample contains an application allowing users to request authorization for a registered pCloud API application.
• The sample gives a hint on how AuthorizationActivity should be used.

#License Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.