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 oneCalling 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 Method | Purpose | Description |
|---|---|---|
setEndpoint(String) | Set the API root path | e.g. https://appbuild-sit.oceanbase.com/v1 or https://appbuild.oceanbase.com/v1. |
setProject(String) | Set X-Appwrite-Project | Target project ID (e.g. demo project enterprise-ai-hub-210). |
setKey(String) | Set X-Appwrite-Key | Server-side project API Key; skips RLS checks and is authorized with the minimum scope. |
setJWT(String) | Set X-Appwrite-JWT | Executes RLS-constrained server-side calls on behalf of a specific user. |
setSession(String) | Set X-Appwrite-Session | Forwards the browser login session. |
setLocale(String) | Set X-Appwrite-Locale | Specifies the internationalization language (e.g. zh-CN). |
setSelfSigned(boolean) | Self-signed TLS certificate switch | For private test environments only; keep false in production. |
addHeader(String, String) | Append a custom request header | Used 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:
No
Sqlservice (SQL uses the HTTP form or the JS Console SDK, see ../databases/sql-proxy.md).No typed quota/ratelimit methods: use the REST endpoint instead (../limits.md).
The three-level usage method is named
getUsageAggregates(not the JSlistUsageAggregates) — do not guess based on JS naming.
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
Java (Server / Console) complete call syntax: ../examples/java.md