Merge pull request #41 from AzisabaNetwork/feat/define-api

APIを定義する

Author: sysnote8main

README.md

@@ -1 +1,41 @@
 # v2 is under development. Don't use this!!!
+
+## Todo
+- `/kdstatus refresh-cache`の実装
+
+## 開発上の注意
+- パッチバージョンで破壊的変更を行わないでください。
+- 適切なバージョニングを心がけてください。
+- APIの仕様変更をする場合\
+すぐに、APIからメソッドを消すのではなく、`@Deprecated`を2つ以上先のマイナーバージョンに向けて付けること
+
+## APIの仕様
+- このAPIは読み取り専用であり、書き込み等は行えない。
+- APIの使用時には、毎回`KDStatusReloaded.getAPI()`を行うことが推奨される。\
+(プラグインの再読み込み等により、内部の値が変化している可能性があるため)
+- APIは、同じマイナーバージョン内では破壊的変更が行われることはない。
+
+## 運用上の注意
+- APIのキャッシュ等は時間ベースではなく、変化したタイミングで行なっている。 \
+そのため、データベースを直接書き換える等の操作が行われた場合には手動で`/kdstatus refresh-cache`を行う必要性がある。
+- データベースへの接続のヘルスチェックはconfig内で設定された間隔で行います\
+状況に応じて、適切な間隔に設定してください。
+
+## データベース切り替え
+このKDStatusReloadedでは、複数のデータベースがサポートされており、切り替えることができます。\
+切り替えコマンドは、`/kdstatus switch-db <db-alias>`となっています。\
+db-aliasは、
+
+| データベース名 | db-alias |
+|---------|----------|
+| MySQL   | mysql    |
+| MariaDB | mariadb  |
+| SQLite3 | sqlite3  |
+となっています。
+
+## 緊急時
+- メインデータベースへ接続が不可能になった場合には、sqlite3を用いて、ローカルに自動的に保存されます。
+- もしも、APIも何もかも死んだ時には、`/kdstatus force-reload`をかけることでこれらのタスクが走ります。
+  - データベースへ再接続
+  - キャッシュの再取得
+  - APIのリフレッシュ

src/main/java/jp/azisaba/lgw/kdstatus/api/KDAPIInterface.java

@@ -14,18 +14,26 @@
  */
 interface KDAPIInterface {
     /**
-     * Get specific user's data
+     * Get specific user's data. If data wasn't found, create new userdata.
      * @param uuid UUID of player
      * @param name Name of player
+     * @return returns KDUserData.
+     */
+    @NotNull
+    KDUserData getOrCreateUserData(@NotNull UUID uuid, @NotNull String name);
+
+    /**
+     * Get specific user's data
+     * @param uuid UUID of player
      * @return returns KDUserData. If failed, returns null.
      */
     @Nullable
-    KDUserData getUserData(@NotNull UUID uuid, @NotNull String name);
+    KDUserData getUserData(@NotNull UUID uuid);
 
     /**
      * Get specific user's ranking
      * @param uuid UUID of player
-     * @param unit Name of player
+     * @param unit Unit of ranking
      * @return returns ranking order. If failed, returns -1.
      */
     int getRank(@NotNull UUID uuid, @NotNull TimeUnit unit);
@@ -37,4 +45,28 @@ interface KDAPIInterface {
      * @return List of {@link KillRankingData}. If failed, returns empty list.
      */
     List<KillRankingData> getTopKillRankingData(@NotNull TimeUnit unit, int maxSize);
+
+    // === Won't need to implement each ===
+    /**
+     * Get specific user's kill count
+     * @param uuid UUID of player
+     * @param unit Unit of ranking
+     * @return returns kill count. If failed, returns -1.
+     */
+    default int getKills(@NotNull UUID uuid, @NotNull TimeUnit unit) {
+        var userdata = getUserData(uuid);
+        if(userdata == null) return -1;
+        return userdata.getKills(unit);
+    }
+
+    /**
+     * Get specific user's death count
+     * @param uuid UUID of player
+     * @return returns total death count. If failed, returns -1
+     */
+    default int getDeaths(@NotNull UUID uuid) {
+        var userdata = getUserData(uuid);
+        if(userdata == null) return -1;
+        return userdata.getDeaths();
+    }
 }