Java 接入

Java 專案透過 SDK 自帶的 Java 介面（下文稱“門面”）呼叫 SDK，不需要配置 KSP。業務型別大多在 com.deeprespond.im 包中，Java 門面在 com.deeprespond.im.java 包中。Java 和 Kotlin 共用同一份資料、會話、傳送佇列和許可權規則，本頁只講 Java 的寫法。

要做什麼	看哪裡
初始化、取得 Java 門面	初始化與恢復
呼叫非同步方法（回撥或 CompletableFuture）	回撥與 Future
訂閱登入、連線等狀態	狀態訂閱
傳選項、時長引數	引數與 Duration
對照 Kotlin 文件寫 Java	Java 與 Kotlin 對照

初始化與恢復

import android.content.Context;
import com.deeprespond.im.*;
import com.deeprespond.im.java.*;

DRClientOptions options = DRClientOptions.builder("org#app", "https://api.example.com").build();
DRJavaClient im = DRClient.initialize(context, options).java();
im.auth().awaitRestored(new DRCallback<Void>() {
    public void onSuccess(Void ignored) {
        // 恢复后再根据 im.auth().getCurrentUser() 决定是否登录。
    }
    public void onError(DRException error) { /* 处理恢复失败 */ }
});

請在使用者同意隱私政策後、在 App 的主程序中初始化。之後用 DRClient.getInstance().java() 取得同一個客戶端的 Java 門面；還沒初始化時 getInstance() 丟擲 IllegalStateException。

回撥與 Future

import com.deeprespond.im.*;
import com.deeprespond.im.java.*;

DRCancellable pending = im.auth().loginWithTicket(ticket, new DRCallback<LoginResult>() {
    public void onSuccess(LoginResult result) { /* 默认回调在主线程 */ }
    public void onError(DRException error) { /* 按 code 和 reason 判断 */ }
});
// 页面不再需要等待时：pending.cancel();

• 每個非同步方法有兩種呼叫方式：傳回撥（返回 DRCancellable），或呼叫 ...Async() 得到 CompletableFuture。
• 沒有返回值的方法用 DRCallback<Void>，成功時的值為 null。
• 回撥預設在主執行緒執行；withExecutor 可以指定回撥和監聽在哪個 Executor 上執行。
• Kotlin 的可選引數在 Java 中對應過載方法或 Params 引數類（見下），請以編輯器的提示為準，不要照著 Kotlin 的引數位置去猜。
• CompletableFuture 在 SDK 的執行緒上完成，更新介面前要切回主執行緒（withExecutor 隻影響回撥和監聽，不影響 Future）。取消 Future 用 cancel(true)。

import com.deeprespond.im.*;
import java.util.concurrent.CompletableFuture;

CompletableFuture<LoginResult> future = im.auth().loginWithTicketAsync(ticket);
future.whenComplete((result, error) -> {
    if (error != null) {
        // 处理异常；这里不能直接修改 Android View。
    } else {
        System.out.println(result.getSessionId());
    }
});

有多個可選引數時，用所屬門面的 Params.builder()，例如查詢公開群：

import com.deeprespond.im.java.*;

DRGroupsModule.PublicGroupsParams params = DRGroupsModule.PublicGroupsParams.builder()
    .namePrefix("项目")
    .limit(20)
    .build();
im.groups().publicGroupsAsync(params);

DRCancellable.cancel() 只是不再等待：已經進入佇列的訊息、已經發出的寫操作仍按 SDK 的規則繼續。上傳、下載要真正取消，呼叫任務自己的 cancel。

狀態訂閱

import com.deeprespond.im.java.*;

DRSubscription subscription = im.auth().observeState(state -> {
    // 更新登录界面。
});
subscription.close(); // 实际在页面退出时关闭。

門面為每個狀態提供同步的 getXxx() 和持續訂閱的 observeXxx()。getXxx() 只返回撥用時的值，不會自動更新；訂閱不用時必須 close()。示例 App 的 Java 頁面演示了恢復、訂閱、診斷和非同步呼叫。

引數與 Duration

• DRClientOptions 用 builder(appKey, apiUrl)，DRPushOptions 用 builder(credentials)，DRCallOptions 和 MediaOptions 用 builder()。
• Kotlin 中的 Duration 引數，在 Java 中用毫秒的版本，如 userCacheTtlMillis、retryAfterMillis、OutgoingContent.voice(file, durationMs)、DndChange.On.ofMillis(durationMs)。

import com.deeprespond.im.*;

MediaOptions media = MediaOptions.builder()
    .preprocess((file, kind, callback) -> callback.onSuccess(file))
    .build();

• preprocess 替換 SDK 預設的媒體處理，檔案能否讀取、後設資料是否清除都由你負責。上例只演示寫法，原樣返回檔案並不會清除後設資料。
• ticketProvider 在 Java 中用 JavaTicketProvider 回撥，把業務服務端簽發的憑證傳回。

各模組的含義見對應的章節，完整的 Kotlin 簽名見介面參考。

Java 與 Kotlin 對照

Kotlin	Java 門面或規則
DRClient	DRJavaClient，透過 client.java() 獲取
AuthModule、MessagesModule、GroupsModule 等	DRAuthModule、DRMessagesModule、DRGroupsModule，透過 im.auth() / messages() / groups() 獲取
MessageList、LiveList、CallHandle、ChatroomHandle	DRMessageList、DRLiveList、DRCallHandle、DRChatroomHandle
StateFlow.value	getXXX() 同步讀取，observeXXX(DRListener) 持續訂閱
suspend 方法	回撥方法返回 DRCancellable；Async 方法返回 CompletableFuture
Duration 引數	同名 Java 方法的 Long 引數為毫秒，如 waitUntilReadyAsync(15000L)
CallHandle 的裝置擴充套件	DRJavaCalls 靜態方法，例如 switchCameraAsync(handle)、observeAudioEndpoints(handle, listener)
原生推送控制器	DRPush.of(client) 返回 DRPushController；原生掛起呼叫仍按 Kotlin 協程接入

推送的控制器沒有 Java 回撥版本。Java App 可以寫一小段 Kotlin 程式碼處理推送的許可權和登記（它們是掛起函式），再向你的 Java 程式碼提供自己的回撥；控制器上沒有 Async 方法，不要照著其他模組去呼叫。

獨立頻道

頻道的 Java 門面是 DRChannelsModule 和 DRChannelHandle，同樣提供回撥和 Async 兩種方法；observeCurrent、observeSnapshot、observeTracks 返回的 DRSubscription 用完要關閉。

android.os.Handler mainHandler = new android.os.Handler(android.os.Looper.getMainLooper());
java.util.concurrent.Executor mainExecutor = task -> mainHandler.post(task);
DRChannelsModule channels = new DRChannelsModule(
    DRClient.getInstance().getChannels(), mainExecutor);
ChannelJoinOptions options = new ChannelJoinOptions(ticket, null, false, false);
channels.join("meeting-demo", options, new DRCallback<DRChannelHandle>() {
    public void onSuccess(DRChannelHandle channel) {
        // 保存句柄；用户授权后手动启用采集；页面离开时 leave。
    }
    public void onError(DRException error) { /* 展示错误并允许用户决定下一步 */ }
});

ChannelJoinOptions 在 Java 中的構造引數依次為 ticket、clientSessionId、microphoneEnabled、cameraEnabled。介面和許可權的限制與 Kotlin 的頻道相同。