パッケージ com.lmt.lib.bms

クラス BmsObjectFinder<IT,​OT,​CT>

  • 型パラメータ:
    IT - Input Type: 入力データの型
    OT - Output Type: 出力データの型
    CT - Candidate Type: 候補データの型
    直系の既知のサブクラス:
    BmsMaterialFileFinder
    public abstract class BmsObjectFinder<IT,​OT,​CT>
extends Object
    BMSにおけるオブジェクト(主に楽曲データの素材ファイル)の最も一般的な検索アルゴリズムを提供するクラスです。

    BMSでは一般的に、楽曲を構成する素材データファイルは索引付きメタ情報に記述されます。 本来はそのメタ情報に記述した通りの名前でファイルが格納されているべきですが、異なる拡張子・異なるファイル形式の 素材データファイルとして格納されているケースが散見され、アプリケーションはそのケースに対応した機能を提供しなければなりません。 その機能は煩雑かつ複雑であり、アプリケーションの実装・テストのコストを高騰させる要因になりがちです。

    当クラスは上記に係る検索アルゴリズムを抽象化し、各アプリケーションでのオブジェクト検索の実装を簡略化します。 通常、楽曲を構成するオブジェクトはメタ情報の定義と拡張子・ファイル形式が異なっていても、BMSコンテンツごとに見ると その形式が統一されている場合がほとんどです。この特性を利用し、一度特定された形式を記憶しておけばオブジェクト検索の ヒットミスを最小化でき、BMS関連アプリケーション実装の簡略化・高速化を見込めます。

    オブジェクト検索の結果は統計情報として記録されており、各統計情報を参照すれば検索アルゴリズムの妥当性を検証できます。 オブジェクト検索のパフォーマンスが問題になる場合はこの情報を活用して検索アルゴリズム・候補データをチューニングしてください。

    導入されたバージョン:
    0.11.0

    • コンストラクタの概要

      コンストラクタ 
      修飾子 コンストラクタ 説明
      protected BmsObjectFinder​(List<CT> candidates)
      新しいオブジェクト検索クラスインスタンスを生成します。

    • コンストラクタの詳細

      • BmsObjectFinder

        protected BmsObjectFinder​(List<CT> candidates)
        新しいオブジェクト検索クラスインスタンスを生成します。

        候補データは必ず1つ以上指定しなければなりません。

        パラメータ:
        candidates - 候補データリスト
        例外:
        NullPointerException - candidatesがnull
        IllegalArgumentException - candidatesが0件

    • メソッドの詳細

      • getCandidateCount

        public int getCandidateCount()
        候補データの数を取得します。
        戻り値:
        候補データの数

      • getLastCandidate

        public CT getLastCandidate()
        最後にオブジェクトが見つかった時の候補データを取得します。

        まだ一度もオブジェクトが見つかっていない場合、nullを返します。

        戻り値:
        最後にオブジェクトが見つかった時の候補データ

      • getQueryCount

        public long getQueryCount()
        オブジェクト検索を行った回数を取得します。
        戻り値:
        オブジェクト検索を行った回数

      • getFoundCount

        public long getFoundCount()
        オブジェクトが見つかった回数を取得します。
        戻り値:
        オブジェクトが見つかった回数

      • getHitCount

        public long getHitCount()
        前回見つかったオブジェクトの候補と同じ候補でオブジェクトが見つかった回数を取得します。
        戻り値:
        前回見つかったオブジェクトの候補と同じ候補でオブジェクトが見つかった回数

      • getWrongCount

        public long getWrongCount()
        前回見つかったオブジェクトの候補とは異なる候補でオブジェクトが見つかった回数を取得します。
        戻り値:
        前回見つかったオブジェクトの候補とは異なる候補でオブジェクトが見つかった回数

      • reset

        public void reset()
        このオブジェクトの状態をリセットします。

        当メソッドが実行されると一度も候補が見つかっていない状態となり、全ての統計データが初期化されます。

      • find

        public Optional<OT> find​(IT input)
        入力データに該当するオブジェクトの検索を実行します。

        当メソッドは、最初に前回の検索で使用した候補データでの検索を試みます。この検索で該当オブジェクトが 見つからなかった場合のみ他候補データでの検索を実行し、最初に見つかったオブジェクトの出力データを返します。

        オブジェクト検索の結果は統計データとして記録されます。統計データは reset() を実行しない限り その情報のカウンタ値が増加し続けますので、必要なタイミングでリセットするようにしてください。 また、検索処理中に実行時例外がスローされた場合はいずれの統計データも更新されません。

        オブジェクトが見つかると、そのオブジェクトを表すデータ(例：ファイルパス)が返されます。 見つからなかった場合は空オブジェクト(Optional#isEmptyがtrueを返す)が返されます。 戻り値がnullになることはありません。

        パラメータ:
        input - オブジェクトを表すデータ(例：ファイルパス)
        戻り値:
        オブジェクト検索結果
        例外:
        NullPointerException - inputがnull

      • doFind

        protected abstract OT doFind​(IT input,
                             CT candidate)
        指定された候補データによる実際のオブジェクト検索処理の実装です。

        入力データに対して候補データを適用し、検索処理を実行してください。該当するオブジェクトが存在する場合は そのオブジェクトを表す出力データを返し、存在しない場合はnullを返してください。

        当メソッド内でスローされた実行時例外は全て find(Object) の呼び出し元へそのままスローされます。 オブジェクト検索処理内でスローされ得る例外は当メソッド内でキャッチし、適切な処理を行うようにしてください。

        パラメータ:
        input - 入力データ
        candidate - 候補データ
        戻り値:
        inputに該当するオブジェクトが存在すれば、それに該当する出力データ。存在しなければnull。