/**
* Cookieを用いた人狼BBSサーバとの認証管理を行う。
*
+ * <p>Cookie管理はVM内で共有される。
+ *
* <p>2012-10現在、サポートするのはG国のみ。
*
* <p>2012-10より、Cookie "uniqID" の送出も必要になった模様。
+ *
+ * <p>2020-02現在、認証が必要なHTTP通信は発生しない。
*/
public class AuthManager{
/**
* コンストラクタ。
+ *
* @param bbsUri 人狼BBSサーバURI
* @throws NullPointerException 引数がnull
*/
/**
* コンストラクタ。
+ *
* @param bbsUrl 人狼BBSサーバURL
* @throws NullPointerException 引数がnull
* @throws IllegalArgumentException 不正な書式
/**
* URLからURIへ変換する。
- * 書式に関する例外は非チェック例外へ変換される。
+ *
+ * <p>書式に関する例外は
+ * 非チェック例外{@link IllegalArgumentException}へ変換される。
+ *
* @param url URL
* @return URI
* @throws NullPointerException 引数がnull
/**
* 配列版{@link #encodeForm4Post(java.lang.String)}。
+ *
* @param formData 元の文字列
* @return 符号化された文字列
* @see #encodeForm4Post(java.lang.String)
/**
* ログイン用POSTデータを生成する。
+ *
* @param userID 人狼BBSアカウント名
* @param password パスワード
* @return POSTデータ
/**
* 人狼BBSサーバのベースURIを返す。
+ *
* @return ベースURI
*/
public URI getBaseURI(){
}
/**
- * 人狼BBSサーバ管轄下の全Cookieを列挙する。
- * 他サーバ由来のCookie群との区別はCookieドメイン名で判断される。
+ * この人狼BBSサーバ管轄下の全Cookieを列挙する。
+ *
+ * <p>他サーバ由来のCookie群との区別はCookieドメイン名で判断される。
+ *
* @param cookieStore Cookie記憶域
* @return 人狼BBSサーバ管轄下のCookieのリスト
*/
}
/**
- * 認証Cookieを取得する。
+ * このサーバの認証Cookieを取得する。
*
* <p>G国での認証Cookie名は"login"。
*
}
/**
- * 現在ログイン中か否か判別する。
+ * このサーバに現在ログイン中か否か認証状態により判別する。
+ *
* @return ログイン中ならtrue
*/
public boolean hasLoggedIn(){
}
/**
- * 認証情報をクリアする。
+ * このサーバの認証情報をクリアする。
+ *
+ * <p>以降、BBSサーバへ認証情報は送られなくなる。
+ *
+ * <p>ログアウトと同じ意味。
*/
public void clearAuthentication(){
assert COOKIE_MANAGER == CookieHandler.getDefault();
/**
* 国ごとの人狼BBSサーバとの通信を一手に引き受ける。
+ *
+ * <p>受信対象はHTMLと各種アイコンJPEG画像。
+ *
+ * <p>プロクシサーバを介したHTTP通信を管理する。
+ *
+ * <p>国ごとに文字コードを保持し、HTML文書のデコードに用いられる。
+ *
+ * <p>画像(40種強)はキャッシュ管理が行われる。
+ *
+ * <p>進行中の村の参加者しか知り得ないHTML要素(赤ログその他)を受信するための
+ * 認証情報をCookieで管理する。
+ * ※ 2020-02現在、進行中の村は存在しないゆえ、
+ * Cookie認証を必要とする国は人狼BBSに存在しない。
+ *
+ * <p>最後にHTTP受信が行われた時刻を保持する。
*/
public class ServerAccess{
/**
* 人狼BBSサーバとの接続管理を生成する。
- * この時点ではまだ通信は行われない。
+ *
+ * <p>この時点ではまだ通信は行われない。
+ *
* @param baseURL 国別のベースURL
* @param charset 国のCharset
* @throws IllegalArgumentException 不正なURL
/**
* 画像キャッシュを検索する。
+ *
+ * <p>キーは画像URL文字列。
+ *
+ * <p>ソフト参照オブジェクトの解放などにより、
+ * キャッシュの状況は変化する。
+ *
* @param key キー
* @return キャッシュされた画像。キャッシュされていなければnull。
*/
}
/**
- * 画像キャッシュに登録する。
+ * キャッシュに画像を登録する。
+ *
+ * <p>キーは画像URL文字列。
+ *
* @param key キー
* @param image キャッシュしたい画像。
*/
}
/**
- * HTTP-Proxyを返す。
+ * HTTP通信に使われるProxyを返す。
+ *
* @return HTTP-Proxy
*/
public Proxy getProxy(){
}
/**
- * HTTP-Proxyを設定する。
+ * HTTP通信に使われるProxyを設定する。
+ *
* @param proxy HTTP-Proxy。nullならProxyなしと解釈される。
*/
public void setProxy(Proxy proxy){
/**
* 国のベースURLを返す。
+ *
* @return ベースURL
*/
public URL getBaseURL(){
/**
* 与えられたクエリーとCGIのURLから新たにURLを合成する。
+ *
* @param query クエリー
* @return 新たなURL
*/
}
/**
- * エンコーディングされた入力ストリームから文字列を生成する。
+ * エンコーディングされた入力ストリームからHTML文字列を受信する。
+ *
* @param istream 入力ストリーム
* @return 文字列
* @throws java.io.IOException 入出力エラー(おそらくネットワーク関連)
/**
* 与えられたクエリーを用いてHTMLデータを取得する。
+ *
* @param query HTTP-GET クエリー
* @return HTMLデータ
* @throws java.io.IOException ネットワークエラー
/**
* 与えられたURLを用いてHTMLデータを取得する。
+ *
* @param url URL
* @return HTMLデータ
* @throws java.io.IOException ネットワークエラー
/**
* 絶対または相対URLの指すパーマネントなイメージ画像をダウンロードする。
+ *
* @param url 画像URL文字列
* @return 画像イメージ
* @throws java.io.IOException ネットワークエラー
/**
* 指定された認証情報をPOSTする。
+ *
+ * <p>ログイン動作を模した物。
+ *
* @param authData 認証情報
* @return 認証情報が受け入れられたらtrue
* @throws java.io.IOException ネットワークエラー
/**
* トップページのHTMLデータを取得する。
+ *
* @return HTMLデータ
* @throws java.io.IOException ネットワークエラー
*/
/**
* 国に含まれる村一覧HTMLデータを取得する。
+ *
+ * <p>wolf国には存在しない。
+ *
* @return HTMLデータ
* @throws java.io.IOException ネットワークエラー
*/
/**
* 指定された村のPeriod一覧のHTMLデータを取得する。
- * 現在ゲーム進行中の村にも可能。
+ *
+ * <p>現在ゲーム進行中の村にも可能。
* ※ 古国では使えないよ!
+ *
* @param village 村
* @return HTMLデータ
* @throws java.io.IOException ネットワークエラー
/**
* 指定された村の最新PeriodのHTMLデータをロードする。
- * 既にGAMEOVERの村ではPeriod一覧のHTMLデータとなる。
+ *
+ * <p>既にGAMEOVERの村ではPeriod一覧のHTMLデータとなる。
+ *
* @param village 村
* @return HTMLデータ
* @throws java.io.IOException ネットワークエラー
/**
* 指定された村の最新PeriodのHTMLデータのURLを取得する。
+ *
* @param village 村
* @return URL
*/
/**
* 指定されたPeriodのHTMLデータをロードする。
+ *
* @param period Period
* @return HTMLデータ
* @throws java.io.IOException ネットワークエラー
/**
* 指定されたPeriodのHTMLデータのURLを取得する。
+ *
* @param period 日
* @return URL
*/
/**
* 最終アクセス時刻を更新する。
+ *
* @param connection HTTP接続
* @return リソース送信時刻
*/
}
/**
- * 与えられたユーザIDとパスワードでログイン処理を行う。
+ * 与えられたユーザIDとパスワードでログイン処理と認証を行う。
+ *
+ * <p>すでに認証済みならなにもしない。
+ *
* @param userID ユーザID
* @param password パスワード
* @return ログインに成功すればtrue
/**
* ログアウト処理を行う。
+ *
+ * <p>認証済みでなければなにもしない。
+ *
* @throws java.io.IOException ネットワーク入出力エラー
*/
public void logout() throws IOException{
// TODO シャットダウンフックでログアウトさせようかな…
/**
- * ログイン中か否か判定する。
+ * ログイン中か否か認証情報で判定する。
+ *
* @return ログイン中ならtrue
*/
public boolean hasLoggedIn(){