> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dragdropdo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Java SDK

> The official `dragdropdo-sdk` package provides a high‑level interface to the D3 Business API.

## Installation

Add the following dependency to your `pom.xml`:

```xml theme={null}
<dependency>
    <groupId>com.d3</groupId>
    <artifactId>dragdropdo-sdk</artifactId>
    <version>1.0.0</version>
</dependency>
```

Or for Gradle:

```gradle theme={null}
implementation 'com.d3:dragdropdo-sdk:1.0.0'
```

## Quick start

```java theme={null}
import com.dragdropdo.sdk.Dragdropdo;
import com.dragdropdo.sdk.DragdropdoConfig;
import com.dragdropdo.sdk.models.*;

// Initialize the client
Dragdropdo client = new Dragdropdo(
    new DragdropdoConfig("your-api-key-here")
        .setBaseUrl("https://api.dragdropdo.com")  // Optional, defaults to https://api.dragdropdo.com
        .setTimeout(30000)                 // Optional, defaults to 30000ms
);

// Upload a file
UploadResponse uploadResult = client.uploadFile(
    new UploadFileOptions()
        .setFile("/path/to/document.pdf")
        .setFileName("document.pdf")
        .setMimeType("application/pdf")
);

System.out.println("File key: " + uploadResult.getFileKey());
```

## Initialization

```java theme={null}
new Dragdropdo(DragdropdoConfig config)
```

**Config:**

* `apiKey` (**required**) – your D3 API key.
* `baseUrl` (optional) – API base URL, default: `https://api.dragdropdo.com`.
* `timeout` (optional) – request timeout in ms, default: `30000`.
* `headers` (optional) – additional headers to send with every request.

## File upload

```java theme={null}
uploadFile(UploadFileOptions options)
```

**Options:**

* `file` (**required**) – file path string.
* `fileName` (**required**) – original file name.
* `mimeType` (optional) – MIME type (auto‑detected if omitted).
* `parts` (optional) – number of upload parts (auto‑calculated).
* `onProgress` (optional) – progress callback (`Consumer<UploadProgress>`).

Example:

```java theme={null}
UploadResponse result = client.uploadFile(
    new UploadFileOptions()
        .setFile("/path/to/file.pdf")
        .setFileName("document.pdf")
        .setMimeType("application/pdf")
        .setOnProgress(progress ->
            System.out.println("Upload: " + progress.getPercentage() + "%")
        )
);
```

## Supported operations

```java theme={null}
checkSupportedOperation(SupportedOperationOptions options)
```

**Options:**

* `ext` (**required**) – file extension (e.g. `pdf`, `jpg`).
* `action` (optional) – specific action (`convert`, `compress`, ...).
* `parameters` (optional) – parameters to validate (e.g. `Map.of("convert_to", "png")`).

Examples:

```java theme={null}
// Get available actions for PDF
SupportedOperationResponse actions = client.checkSupportedOperation(
    new SupportedOperationOptions().setExt("pdf")
);
System.out.println(actions.getAvailableActions());

// Check if convert to PNG is supported
SupportedOperationResponse supported = client.checkSupportedOperation(
    new SupportedOperationOptions()
        .setExt("pdf")
        .setAction("convert")
        .setParameters(Map.of("convert_to", "png"))
);
System.out.println("Supported: " + supported.isSupported());
```

## Create operations

```java theme={null}
createOperation(OperationOptions options)
```

**Options:**

* `action` (**required**) – `"convert" | "compress" | "merge" | "zip" | "lock" | "unlock" | "reset_password"`.
* `fileKeys` (**required**) – list of file keys from upload.
* `parameters` (optional) – action‑specific parameters.
* `notes` (optional) – user metadata.

Examples:

```java theme={null}
// Convert PDF to PNG
client.createOperation(new OperationOptions(
    "convert",
    List.of(uploadResult.getFileKey()),
    Map.of("convert_to", "png"),
    Map.of("userId", "user-123")
));

// Compress
client.createOperation(new OperationOptions(
    "compress",
    List.of(uploadResult.getFileKey()),
    Map.of("compression_value", "recommended"),
    null
));
```

### Convenience helpers

The client exposes shorthand helpers:

```java theme={null}
client.convert(fileKeys, convertTo, notes)
client.compress(fileKeys, compressionValue, notes)
client.merge(fileKeys, notes)
client.zip(fileKeys, notes)
client.lockPdf(fileKeys, password, notes)
client.unlockPdf(fileKeys, password, notes)
client.resetPdfPassword(fileKeys, oldPassword, newPassword, notes)
```

## Status & polling

```java theme={null}
getStatus(StatusOptions options)
pollStatus(PollStatusOptions options)
```

**`StatusOptions`** (used by `getStatus`):

* `mainTaskId` (**required**) – set via `setMainTaskId(String)`.
* `fileKey` (optional) – set via `setFileKey(String)` when you need status for a specific input file.

**`PollStatusOptions`** (extends `StatusOptions`; used by `pollStatus`):

* Same setters as `StatusOptions`, plus:
* `interval` (optional) – milliseconds between polls, default `2000` if unset (`setInterval(long)`).
* `timeout` (optional) – maximum total polling time in milliseconds, default `300000` if unset (`setTimeout(long)`).
* `onUpdate` (optional) – `Consumer<StatusResponse>` for each successful status fetch (`setOnUpdate`).

Examples:

```java theme={null}
// Single status fetch
StatusResponse status = client.getStatus(
    new StatusOptions().setMainTaskId("task-123")
);

// Poll until completion
StatusResponse finalStatus = client.pollStatus(
    new PollStatusOptions()
        .setMainTaskId("task-123")
        .setInterval(2000)
        .setTimeout(300000)
        .setOnUpdate(s -> System.out.println("Status: " + s.getOperationStatus()))
);
```

## Complete workflow example

```java theme={null}
import com.dragdropdo.sdk.Dragdropdo;
import com.dragdropdo.sdk.DragdropdoConfig;
import com.dragdropdo.sdk.models.*;
import com.dragdropdo.sdk.exceptions.*;
import java.util.*;

public class Example {
    public static void main(String[] args) {
        Dragdropdo client = new Dragdropdo(
            new DragdropdoConfig(System.getenv("D3_API_KEY"))
                .setBaseUrl("https://api.dragdropdo.com")
        );

        try {
            // 1. Upload
            UploadResponse uploadResult = client.uploadFile(
                new UploadFileOptions()
                    .setFile("./document.pdf")
                    .setFileName("document.pdf")
            );

            // 2. Check support
            SupportedOperationResponse supported = client.checkSupportedOperation(
                new SupportedOperationOptions()
                    .setExt("pdf")
                    .setAction("convert")
                    .setParameters(Map.of("convert_to", "png"))
            );
            if (!supported.isSupported()) {
                throw new Exception("Convert to PNG is not supported");
            }

            // 3. Create operation
            OperationResponse operation = client.convert(
                List.of(uploadResult.getFileKey()),
                "png",
                Map.of("userId", "user-123", "source", "api")
            );

            // 4. Poll
            StatusResponse status = client.pollStatus(
                new PollStatusOptions()
                    .setMainTaskId(operation.getMainTaskId())
                    .setInterval(2000)
            );

            if ("completed".equals(status.getOperationStatus())) {
                status.getFilesData().forEach(file ->
                    System.out.println("Download: " + file.getDownloadLink())
                );
            }
        } catch (D3APIError e) {
            System.out.println("API Error (" + e.getStatusCode() + "): " + e.getMessage());
        } catch (D3ValidationError e) {
            System.out.println("Validation Error: " + e.getMessage());
        } catch (Exception e) {
            System.out.println("Error: " + e.getMessage());
        }
    }
}
```