インタフェース 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
に 内包されて呼び出し元へスローします。本来、当インターフェイスが提供するメソッドでは例外がスローされることは想定していません。
-
-
ネストされたクラスの概要
ネストされたクラス 修飾子とタイプ インタフェース 説明 static class
BmsLoadHandler.TestResult
BMS宣言、メタ情報、チャンネルデータの検査結果を示す列挙です。
-
メソッドの概要
すべてのメソッド インスタンス・メソッド デフォルト・メソッド 修飾子とタイプ メソッド 説明 default BmsContent
createContent(BmsSpec spec)
BMSコンテンツオブジェクトを生成します。default BmsNote
createNote()
ノートオブジェクトを生成します。default boolean
finishLoad(BmsContent content)
BmsLoader.load(java.io.File)
にてBMSの読み込み処理が完了した時に一度だけ呼び出されます。default boolean
parseError(BmsLoadError error)
BMS読み込み中にソース解析エラーが発生した場合に呼び出されます。default void
startLoad(BmsSpec spec)
BmsLoader.load(java.io.File)
にてBMSの読み込み処理が開始された時に一度だけ呼び出されます。default BmsLoadHandler.TestResult
testChannel(BmsChannel channel, int index, int measure, Object value)
1個のチャンネルデータを解析した時に呼び出されます。default BmsLoadHandler.TestResult
testDeclaration(String key, String value)
1個のBMS宣言を解析した時に呼び出されます。default BmsLoadHandler.TestResult
testMeta(BmsMeta meta, int index, Object value)
1個のメタ情報を解析した時に呼び出されます。
-
-
-
メソッドの詳細
-
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
-
-