README.md

RDP SDK for Java/Kotlin

The RDP SDK for Java/Kotlin is part of the unified SDK family for client applications interacting with Raft Data Platform (RDP). It provides Kotlin-first APIs, Java-friendly blocking support, and generated service clients for the RDP API surface.

For platform concepts, API guides, and integration details, see https://developer.teamraft.com.

Installation

Add the SDK as a Gradle dependency:

repositories {
    mavenCentral()
    maven {
        name = "buf"
        url = uri("https://buf.build/gen/maven")
    }
}

dependencies {
    implementation("com.teamraft:rdp-sdk-java:<version>")
}

The Buf Maven repository provides the public Java and Kotlin packages generated from the raft/wdm module. The generated packages use the build.buf.gen.raft.wdm.v1 namespace shown below.

Quick Start

export RDP_SERVER_URL=https://rdp.example.com
export RDP_API_KEY=your-api-key

Kotlin:

import com.raft.rdp.loadConfig
import build.buf.gen.raft.wdm.v1.service.SearchObjectsRequest
import com.raft.rdp.toOptions
import com.raft.rdp.v1.RdpClient

suspend fun main() {
    // Load RDP_SERVER_URL and authentication from the environment.
    val cfg = loadConfig()

    // Create a client from the loaded config.
    RdpClient.create(cfg.toOptions()).use { client ->
        // Request the first 10 WDM objects.
        val response = client.objectService.searchObjects(
            SearchObjectsRequest.newBuilder()
                .setPageSize(10)
                .build(),
        )

        response.success { result ->
            val objects = result.message.objectsList
            if (objects.isEmpty()) {
                println("No WDM objects found.")
                return@success
            }

            objects.forEach { obj ->
                println("${obj.id}\t${obj.name}")
            }
        }
        response.failure { err ->
            error("SearchObjects failed: ${err.cause.message}")
        }
    }
}

Java:

import static com.connectrpc.ResponseMessageKt.getOrThrow;

import com.raft.rdp.Rdp;
import build.buf.gen.raft.wdm.v1.service.SearchObjectsRequest;
import com.raft.rdp.v1.RdpClient;
import java.util.Collections;

public final class Main {
    public static void main(String[] args) {
        // Load RDP_SERVER_URL and authentication from the environment.
        var cfg = Rdp.loadConfig();

        // Create a client from the loaded config.
        try (var client = RdpClient.create(Rdp.toOptions(cfg))) {
            // Request the first 10 WDM objects.
            var response =
                client.getObjectService()
                    .searchObjectsBlocking(
                        SearchObjectsRequest.newBuilder().setPageSize(10).build(),
                        Collections.emptyMap())
                    .execute();

            var objects = getOrThrow(response).getObjectsList();
            if (objects.isEmpty()) {
                System.out.println("No WDM objects found.");
                return;
            }

            for (var object : objects) {
                System.out.printf("%s\t%s%n", object.getId(), object.getName());
            }
        }
    }
}

For more examples, see examples.

Configuration

loadConfig() reads connection settings from environment variables and returns a validated RdpConfig. Process environment values take precedence over values loaded from .env.local or a custom dotenv path.

Variable	Required	Description
RDP_SERVER_URL	No	Base RDP endpoint. Defaults to https://rdp.local; use scheme and host only.
RDP_SERVER_PORT	No	Optional port override for the endpoint.
TLS_SKIP_VERIFY	No	Set to true only for development or test endpoints with self-signed certificates.

Authentication

API key authentication is the preferred method for client applications. Use OAuth2 client credentials or a static Bearer token only when your deployment requires it.

Method	Variables	Request behavior
API key	RDP_API_KEY	Sends the value on each request as an API key header.
OAuth2 client credentials	RDP_CLIENT_ID, RDP_CLIENT_SECRET	Fetches a token from {RDP_SERVER_URL}/api/v1/auth/token and sends it as a bearer token.
Bearer	RDP_BEARER_TOKEN	Sends Authorization: Bearer <token>.

Providing multiple auth methods is an error. If no method is configured, requests are sent without auth and the SDK logs a warning.

Functional Configuration

Use RdpOptions in Kotlin, or RdpOptions.Builder in Java, to configure the client directly. cfg.toOptions() converts a loaded RdpConfig into client options before calling RdpClient.create(...).

Kotlin callers can use named parameters:

val logger = LoggerFactory.getLogger("rdp")

val options = RdpOptions(
    endpoint = "https://rdp.example.com",
    apiKey = "your-api-key",
    timeout = Duration.ofSeconds(10),
    logger = logger,
)

RdpClient.create(options).use { client ->
    // call generated service clients
}

Static Authorization header auth can be configured directly as well:

val bearerOptions = RdpOptions(
    endpoint = "https://rdp.example.com",
    bearerToken = "token",
)

Kotlin callers can also start from environment configuration and override only what needs to be programmatic:

val cfg = loadConfig(envPath = ".env.local", logger = logger)
val options = cfg.toOptions().copy(timeout = Duration.ofSeconds(10))

RdpClient.create(options).use { client ->
    // call generated service clients
}

Java callers can use the builder:

var logger = LoggerFactory.getLogger("rdp");

var options = new RdpOptions.Builder()
    .endpoint("https://rdp.example.com")
    .apiKey("your-api-key")
    .timeout(Duration.ofSeconds(10))
    .logger(logger)
    .build();

try (var client = RdpClient.create(options)) {
    // call generated service clients
}

Java callers can configure Bearer auth through the builder:

var bearerOptions = new RdpOptions.Builder()
    .endpoint("https://rdp.example.com")
    .bearerToken("token")
    .build();

Use clientCredentials(...) only when your deployment requires OAuth2 client credentials. Use tlsSkipVerify(true) only for development or test endpoints with self-signed certificates.