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

インタフェース BmsLoadHandler

  • すべてのスーパーインタフェース:
    BmsContent.Creator, BmsNote.Creator
    既知の実装クラスのリスト:
    BeMusicLoadHandler

    public interface BmsLoadHandler
    extends BmsContent.Creator, BmsNote.Creator
    BMSローダーの読み込み処理を制御するハンドラです。

    BmsLoaderによるBMSの読み込み処理をアプリケーションが制御するためのインターフェイスを提供します。 通常、BMSの読み込み処理は指定されたBMS仕様(BmsSpec)に基づいて行われますが、アプリケーション固有の事情により 更に細かくローダーの処理を制御したい場合などに本インターフェイスを介して振る舞いを変更することができます。

    BMSの読み込み処理はデフォルトの動作が定義されており、本インターフェイスにはその動作が実装されています。個々のアプリケーションは 自身の実現したい仕様に基づき、必要な振る舞いのみを変更してください。変更可能な振る舞いについては各メソッドのドキュメントを 変更してください。

    例外のポリシーについて
    当インターフェイスが提供するメソッド内で発生した例外はBmsLoader.load(java.io.File)内でキャッチされ、BmsExceptionに 内包されて呼び出し元へスローします。本来、当インターフェイスが提供するメソッドでは例外がスローされることは想定していません。

    • メソッドの詳細

      • createContent

        default BmsContent createContent​(BmsSpec spec)
        BMSコンテンツオブジェクトを生成します。

        BmsLoaderを通して指定されたソースから解析された各種情報は当メソッドが返したBMSコンテンツオブジェクトに格納されます。 BMSの読み込みが正常に完了した場合、BmsLoader.load(java.io.File)からは当メソッドから返されたオブジェクトの参照を返却します。

        BMSコンテンツに指定するBMS仕様は、パラメータで渡されるオブジェクトを渡してください。例えBMS仕様が全く同じであったとしても、 パラメータで渡されたオブジェクト以外を渡したBMSコンテンツを返した場合、BmsLoader.load(java.io.File)の以後の処理でエラーとなり 読み込み失敗となります。

        定義:
        createContent インタフェース内 BmsContent.Creator
        パラメータ:
        spec - BMS仕様
        戻り値:
        BMSコンテンツオブジェクト
      • createNote

        default BmsNote createNote()
        ノートオブジェクトを生成します。

        配列型チャンネルのデータ要素は全てノートオブジェクトとしてBMSコンテンツ内で管理されます。当メソッドで返されたノートオブジェクトは BMSコンテンツ内に格納されることになります。アプリケーションが個々のノートオブジェクトに何らかの情報を付加してBMSコンテンツ内で管理させたい場合、 当メソッドでBmsNoteを継承したノートオブジェクトを返します。

        付加情報の更新はBmsNote.onCreate()を使用して行ってください。 これらのメソッドはBmsContent内部から呼び出されるよう設計されています。

        原則として、当メソッドが呼び出される度に新しいBmsNoteオブジェクトインスタンスを返却しなければなりません。 生成済みのBmsNoteオブジェクトの参照を返却するとオブジェクト内部のデータが上書きされてしまい、当該オブジェクトを持つBMSコンテンツの データ不整合が発生してしまいます。

        当メソッドで例外をスローした場合、当該例外を内包したBmsExceptionがスローされます。

        定義:
        createNote インタフェース内 BmsNote.Creator
        戻り値:
        ノートオブジェクト
      • startLoad

        default void startLoad​(BmsSpec spec)
        BmsLoader.load(java.io.File)にてBMSの読み込み処理が開始された時に一度だけ呼び出されます。

        当メソッドは1個のBMSの読み込みが開始される度に、アプリケーション固有の何らかの初期化処理を行いたい場合を想定して 用意されています。そのような事情が無い場合は何も行う必要はありません。

        当メソッドで例外がスローすると、後の処理で呼ばれるfinishLoad(com.lmt.lib.bms.BmsContent)は呼ばれず、スローされた例外を内包した BmsExceptionがスローされます。

        パラメータ:
        spec - BMSの読み込みに参照するBMS仕様(NOT null保証)
      • finishLoad

        default boolean finishLoad​(BmsContent content)
        BmsLoader.load(java.io.File)にてBMSの読み込み処理が完了した時に一度だけ呼び出されます。

        アプリケーションは、当メソッドのパラメータで渡されるBMSコンテンツを参照することで、独自の観点でBMSコンテンツの読み込み結果 についての検査を行うことができます。読み込まれたBMSコンテンツが当該アプリケーションの仕様にそぐわない内容であると判定し、 エラーとして結果を破棄したい場合は当メソッドの戻り値をfalseで返してください。そうするとBmsLoader.load(java.io.File)BmsAbortExceptionをスローします。エラー種別はBmsLoadError.Kind.FAILED_TEST_CONTENT として報告されます。

        BmsLoadHandlerのメソッド内で例外をスローした場合、当メソッドは呼び出されず、スローされた例外を内包した BmsExceptionがスローされます。

        当メソッドで例外をスローした場合、当該例外を内包したBmsExceptionがスローされます。

        パラメータ:
        content - BMS読み込みが完了し、完成されたBMSコンテンツオブジェクト
        戻り値:
        trueを返すとBMS読み込み処理を正常終了、falseを返すと異常終了と判定します。
      • parseError

        default boolean parseError​(BmsLoadError error)
        BMS読み込み中にソース解析エラーが発生した場合に呼び出されます。

        アプリケーションは当メソッドのパラメータを参照することでエラー情報にアクセスすることができます。また、エラーを無視して解析を 続行するかどうかをメソッドの戻り値で制御することができます。但し、解析エラーはBMSライブラリ、および(もしかしたら)アプリケーションが BMSコンテンツをBMS仕様に従って適正に読み込めないと判断した時に発生させるものであるため、基本的にはエラーを無視することは あまり推奨されません。

        発生するエラーの種類についてはBmsLoadError.Kindを参照してください。

        当メソッドでfalseを返し、エラーを無視しない場合はBmsLoader.load(java.io.File)BmsAbortException例外を スローし、生成中のBMSコンテンツは破棄します。デフォルトの動作では解析エラーは無視しません。

        当メソッドで例外をスローした場合、当該例外を内包したBmsExceptionがスローされます。

        パラメータ:
        error - エラー情報
        戻り値:
        falseを返すと、読み込み続行不可としてBMS読み込みを停止します。
        関連項目:
        BmsLoadError.Kind
      • testDeclaration

        default BmsLoadHandler.TestResult testDeclaration​(String key,
                                                          String value)
        1個のBMS宣言を解析した時に呼び出されます。

        通常、BMS宣言はBMS仕様に関わらずどのようなキーと値でも受け入れますが、アプリケーションとして個々のBMS宣言の内容を 検査したい場合は当メソッドを用います。検査結果は戻り値でBMSローダに報告します。

        デフォルトの動作では、全てのBMS宣言を受け入れます。

        当メソッドで例外をスローした場合、当該例外を内包したBmsExceptionがスローされます。

        パラメータ:
        key - キー(NOT null保証)
        value - 値(NOT null保証)
        戻り値:
        BmsLoadHandler.TestResult参照
        関連項目:
        BmsLoadHandler.TestResult
      • testMeta

        default BmsLoadHandler.TestResult testMeta​(BmsMeta meta,
                                                   int index,
                                                   Object value)
        1個のメタ情報を解析した時に呼び出されます。

        当メソッドが呼び出される契機は、BMS仕様に定義のあるメタ情報の解析が正常に行われた後です。デフォルトの動作では、 BMS仕様に準拠したメタ情報は全てBMSコンテンツ内に記録されます。アプリケーションが個々のメタ情報に対して固有の検査を行う必要が ある場合は当メソッドで検査処理を実装してください。

        解析されたメタ情報の検査結果は戻り値でBMSローダに報告します。

        BMS仕様に無いメタ情報を検出しても当メソッドは呼び出されず、直接parseError(com.lmt.lib.bms.BmsLoadError)が呼び出されます。

        当メソッドで例外をスローした場合、当該例外を内包したBmsExceptionがスローされます。

        パラメータ:
        meta - メタ情報
        index - インデックス
        value - 解析後の値。データ型は当該メタ情報のデータ型に依存します。
        戻り値:
        BmsLoadHandler.TestResult参照
        関連項目:
        BmsMeta, BmsType, BmsLoadHandler.TestResult
      • testChannel

        default BmsLoadHandler.TestResult testChannel​(BmsChannel channel,
                                                      int index,
                                                      int measure,
                                                      Object value)
        1個のチャンネルデータを解析した時に呼び出されます。

        当メソッドが呼び出される契機は、BMS仕様に定義のあるチャンネルが正常に解析された後です。デフォルトの動作では BMS仕様に準拠したチャンネルデータは全てBMSコンテンツ内に記録されます。アプリケーションが個々のチャンネルデータに対して 固有の検査を行う必要がある場合は当メソッドで検査処理を実装してください。

        解析されたチャンネルデータの検査結果は戻り値でBMSローダに報告します。

        BMS仕様に無いチャンネルを検出しても当メソッドは呼び出されず、直接parseError(com.lmt.lib.bms.BmsLoadError)が呼び出されます。

        当メソッドで例外をスローした場合、当該例外を内包したBmsExceptionがスローされます。

        パラメータ:
        channel - チャンネル
        index - チャンネルインデックス
        measure - 小節番号
        value - チャンネルの値。データ型は当該チャンネルのデータ型に依存します。
        戻り値:
        BmsLoadHandler.TestResult参照
        関連項目:
        BmsChannel, BmsType, BmsLoadHandler.TestResult