ChatClient.java

/**
 * Week 7 Workshop 主題：聊天「客戶端程式庫」的介面設計。
 *
 * 專案目標是「任何人的 UI 都能接上任何人的客戶端程式庫」，
 * 所以 UI 只能依賴這個介面，絕對不能依賴某個特定實作類別。
 *
 * 設計重點：
 *   - 方法對應「使用者能做的事」（登入、加入房間、發言、離開），而不是協定細節。
 *   - 伺服器主動推來的事件（別人的訊息、錯誤、斷線）用「監聽者」（listener）回呼，
 *     因為 UI 不可能知道訊息何時會到。
 */
public interface ChatClient {

    /** 事件監聯者：UI 實作這個介面，客戶端程式庫在事件發生時呼叫它。 */
    interface Listener {
        void onMessage(String room, String from, String text);
        void onError(int code, String text);
        void onDisconnected();
    }

    /** 註冊監聽者（可註冊多個）。 */
    void addListener(Listener listener);

    /**
     * 連線並登入。
     * @throws java.io.IOException 網路失敗時
     * @throws IllegalStateException 若已經連線
     */
    void connect(String host, int port, String name) throws java.io.IOException;

    void join(String room);

    /** 前置條件：已連線且已 join 該房間。 */
    void say(String room, String text);

    /** 告知伺服器離開並關閉連線；之後任何操作都是 IllegalStateException。 */
    void disconnect();

    boolean isConnected();
}