Docs
Contents

Server SDK(Java)

Java backends / tools call the Server SDK (io.agentbase:agentbase-java-sdk) with a project API Key. API Key requests skip row-level permission checks (hasRole) and should only be stored on controlled servers. For the Node / Python / Go surfaces see nodejs.md / python.md / go.md in the same directory.

Artifacts and installation

The Java SDK is released as a ZIP delivery package (not published to a Maven registry), hosted on agentbase-sdks release v2.10.0; for download, two-layer SHA256SUMS verification and complete mvn install:install-file steps, see ../integration.md (Path Two) and ../examples/java.md "Acquisition and verification". Runtime: Java 11 source/target (runs on OpenJDK 11/17); the transport is OkHttp (the unpacked directory lib/ carries runtime dependencies; when using the JAR directly you must distribute lib/ together with it).

Initialization

import io.agentbase.Client;
import io.agentbase.services.TablesDB;
import io.agentbase.Query;
import io.agentbase.ID;

Client client = new Client()
    .setEndpoint(System.getenv("APPBASE_ENDPOINT"))   // https://appbuild.oceanbase.com/v1
    .setProject(System.getenv("APPBASE_PROJECT_ID"))
    .setKey(System.getenv("APPBASE_API_KEY"));        // Project API Key with minimal scope

TablesDB tables = new TablesDB(client);               // Construct services one by one

Calling style: methods use synchronous positional parameters, returning a typed model or Map<String,Object> by default; use the new TypeToken<MyPojo>(){}.getType() overload for custom POJOs.

Custom Token issuance

Users users = new Users(client);
Token token = users.createToken("<userId>", null, null);   // { secret, expire }
// Use the Client SDK in the browser: account.createSession({ userId, secret: token.secret })

users.createJWT issues short-lived JWTs (about 15 minutes) to users for service-to-service calls carrying user identity; it is not a Session channel; the Tokens service issues Storage file temporary tokens and is unrelated to user tokens.

Client configuration, timeout, and type deserialization conventions

io.agentbase.Client is built on OkHttp and supports chained configuration of auth headers, language, self-signed certificates, and underlying connection pool parameters:

Client MethodPurposeDescription
setEndpoint(String)Set the API root pathe.g. https://appbuild-sit.oceanbase.com/v1 or https://appbuild.oceanbase.com/v1.
setProject(String)Set X-Appwrite-ProjectTarget project ID (e.g. demo project enterprise-ai-hub-210).
setKey(String)Set X-Appwrite-KeyServer-side project API Key; skips RLS checks and is authorized with the minimum scope.
setJWT(String)Set X-Appwrite-JWTExecutes RLS-constrained server-side calls on behalf of a specific user.
setSession(String)Set X-Appwrite-SessionForwards the browser login session.
setLocale(String)Set X-Appwrite-LocaleSpecifies the internationalization language (e.g. zh-CN).
setSelfSigned(boolean)Self-signed TLS certificate switchFor private test environments only; keep false in production.
addHeader(String, String)Append a custom request headerUsed to inject distributed tracing headers or custom idempotency identifiers.

5-minute end-to-end example (create table, write rows, cursor pagination, and file upload)

The following example demonstrates operating on the support ticket table customer_tickets of the business database enterprise_biz_db in the demo project enterprise-ai-hub-210, using cursor pagination (Query.cursorAfter) and InputFile to upload files:

import io.agentbase.Client;
import io.agentbase.ID;
import io.agentbase.Query;
import io.agentbase.exceptions.AppBaseException;
import io.agentbase. models.InputFile;
import io.agentbase.models.Row;
import io.agentbase.models.RowList;
import io.agentbase.services.Storage;
import io.agentbase.services.TablesDB;

import java.io.File;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class EnterpriseTicketExample {
    public static void main(String[] args) throws Exception {
        Client client = new Client()
            .setEndpoint(System.getenv().getOrDefault("APPBASE_ENDPOINT", "https://appbuild-sit.oceanbase.com/v1"))
            .setProject(System.getenv().getOrDefault("APPBASE_PROJECT_ID", "enterprise-ai-hub-210"))
            .setKey(System.getenv("APPBASE_API_KEY"));

        TablesDB tables = new TablesDB(client);
        Storage storage = new Storage(client);

        // 1. Write an enterprise customer support ticket row
        Row created = tables.createRow(
            "enterprise_biz_db",
            "customer_tickets",
            ID.unique(),
            Map.of(
                "ticketNo", "TK-20261022-005",
                "title", "OceanBase 向量索引构建参数咨询",
                "status", "open",
                "priority", "high"
            ),
            List.of("read(\"any\")")
        );
        System.out.println("Created row ID: " + created.getId());

        // 2. Use Query.cursorAfter cursor pagination to fetch all open support tickets (disable the total count to improve performance)
        String cursor = null;
        long pageSize = 50L;
        while (true) {
            List<String> queries = new ArrayList<>();
            queries.add(Query.equal("status", List.of("open", "in_progress")));
            queries.add(Query.orderAsc("$id"));
            queries.add(Query.limit(pageSize));
            if (cursor != null) {
                queries.add(Query.cursorAfter(cursor));
            }

            RowList<Map<String, Object>> page = tables.listRows(
                "enterprise_biz_db",
                "customer_tickets",
                queries,
                null,
                false // total=false avoids the count(*) overhead on large tables
            );
            List<Row<Map<String, Object>>> rows = page.getRows();
            if (rows.isEmpty()) {
                break;
            }
            for (Row<Map<String, Object>> row : rows) {
                System.out.println("Ticket: " + row.getId() + " -> " + row.getData().get("title"));
            }
            if (rows.size() < pageSize) {
                break;
            }
            cursor = rows.get(rows.size() - 1).getId();
        }

        // 3. Upload local documents to the knowledge base source file bucket kb_enterprise_docs
        var uploaded = storage.createFile(
            "kb_enterprise_docs",
            ID.unique(),
            InputFile.fromFile(new File("/tmp/智能客服SOP标准作业手册.md")),
            null
        );
        System.out.println("Uploaded file ID: " + uploaded.getId());
    }
}

Production retry and exception handling conventions

All service methods in the Java SDK throw the checked exception io.agentbase.exceptions.AppBaseException when a non-2xx response is encountered. Production code should use e.getCode() to distinguish idempotently retryable errors (429 rate limiting, 502/503/504 gateway transients or read-only switchover draining) from non-retryable caller errors (400 invalid parameters, 401/403 missing Key or scope, 404 resource not found, 409 unique key or version conflict):

public static <T> T executeWithRetry(java.util.concurrent.Callable<T> action, int maxAttempts) throws Exception {
    for (int attempt = 1; attempt <= maxAttempts; attempt++) {
        try {
            return action.call();
        } catch (io.agentbase.exceptions.AppBaseException e) {
            int code = e.getCode() != null ? e.getCode() : 0;
            boolean retryable = (code == 429 || code == 502 || code == 503 || code == 504);
            if (!retryable || attempt == maxAttempts) {
                throw e;
            }
            Thread.sleep(Math.min(1000L * (1L << (attempt - 1)), 8000L));
        }
    }
    throw new IllegalStateException("Unreachable");
}

Feature surface navigation

The service surface is isomorphic to the Node surface (PascalCase classes, camelCase methods); for the full mapping see nodejs.md "Feature surface navigation"; feature pages: Databases, Storage, Functions, Sites, Users, Teams, Messaging, memory, knowledge base, LLM Gateway, AI Gateway, Observability, Moderation, Cross-cutting services.

Java-surface-specific differences:

Using alongside the Console SDK

The two SDKs' Client share the same name but have independent namespaces (io.agentbase.Client vs io.agentbase.console.Client, see ../console-sdk/java.md). In the same Java file, import only one and use the fully qualified class name for the other; mixing models / enums / services between the two is forbidden.

Error Handling

try {
    tables.getRow("app-db", "tasks", rowId, null, null);
} catch (io.agentbase.exceptions.AppBaseException e) {
    System.err.println("HTTP " + e.getCode() + " type=" + e.getType() + " msg=" + e.getMessage());
    // 413 storage quota exceeded / 429 rate limited / 401·403 authentication or scope
}

Example Guide