VCSSL/Vnano プラグイン インターフェース 仕様書

# Engine Connector Interface 1 (ECI1)
インターフェース仕様書
(org.vcssl.connect.EngineConnectorInterface1)

## 概要

Engine Connector Interface 1 (ECI1) は、 スクリプトエンジンとプラグインとの間における、いくつかの情報のやり取りを仲介するためのインターフェースです。

スクリプトエンジンは、このインターフェースを実装したオブジェクトを、 各プラグインの初期化/終了時処理のメソッドの引数として渡します。

## ステータス

このインターフェースの現在のステータスは "FINALIZED"（確定済み）です。

このインターフェースの仕様は、2022年8月31日時点で最終確定しました。今後は原則として、ドキュメントやコメント類以外の変更は加えられません。

現在は Vnano のスクリプトエンジンでサポートされ、同エンジンを搭載したアプリケーションのプラグイン開発において利用できます。

## ライセンス

このインターフェースは、実質的な著作権フリー/パブリックドメインである CC0 に基づいて公開されています。

## フィールド/メソッド等の一覧

INTERFACE_TYPE_ID
  プラグインのロード時に参照される、このインターフェースの形式ID（値: "ECI"）です。
INTERFACE_GENERATION
  このインターフェースの世代名です（値: "1"）。
boolean hasOptionValue(String optionName)
  指定された名称のオプションの値が、設定されているかどうかを返します。
Object getOptionValue(String optionName)
  指定されたオプションの値を取得します。
void requestPermission(String permissionName, Object requester, Object metaInformation)
  指定されたパーミッションを要求します。
isOtherEngineConnectorAvailable(Class<?> engineConnectorClass)
  他種のエンジンコネクターが利用可能かどうかを返します。
<T> T getOtherEngineConnector(Class<T> engineConnectorClass)
  他種のエンジンコネクターを返します。

## フィールド

名前 | INTERFACE_TYPE_ID
--- | ---
値の意味 | プラグインのロード時に参照される、このインターフェースの形式ID（値: "ECI"）です。
データ型 | static final String

名前 | INTERFACE_GENERATION
--- | ---
値の意味 | このインターフェースの世代名です（値: "1"）。
データ型 | static final String

## メソッド

名前 | hasOptionValue
--- | ---
宣言形式 | boolean hasOptionValue(String optionName)
機能 | 指定された名称のオプションの値が設定されていて、取得可能な状態であるかどうかを返します。
引数 | optionName: オプションの名称。
戻り値 | 指定されたオプションの値が取得可能な場合に true が返されます。
例外 | なし

名前 | getOptionValue
--- | ---
宣言形式 | Object getOptionValue(String optionName)
機能 | 指定されたオプションの値を取得します。 このメソッドを用いる際には、事前に、指定オプションの値が取得可能である事を、 hasOptionValue(String optionName) メソッドで確認する必要があります。
引数 | optionName: オプションの名称。
戻り値 | 指定されたオプションの値。
例外 | ConnectorFatalException(非検査例外): 指定されたオプションの値が取得不可能な場合にスローされます。

名前 | requestPermission
--- | ---
宣言形式 | void requestPermission(String permissionName, Object requester, Object metaInformation) throws ConnectorException
機能 | 指定されたパーミッションを要求します。 要求したパーミッションが許可された場合は何も起こりませんが、 拒否された場合には、検査例外である ConnectorException が発生します。 要求が許可されるか拒否されるかは、アプリケーション側の設定や、ユーザーの判断などによって決まるため、原則として実行時まで分かりません。 そのため、拒否される可能性を常に想定し、例外を適切にハンドリングしてください。
引数 | permissionName: 要求するパーミッション項目の名称。 requester: パーミッションを要求しているプラグイン。 metaInformation: 必要に応じてユーザーに通知されるメタ情報（特にパーミッション値が ASK の場合などに用いられます）。
戻り値 | なし
例外 | ConnectorException: 要求したパーミッションが拒否された場合にスローされます。

名前 | isOtherEngineConnectorAvailable
--- | ---
宣言形式 | boolean isOtherEngineConnectorAvailable(Class<?> engineConnectorClass)
機能 | 他種のエンジンコネクターが利用可能かどうかを返します。
引数 | engineConnectorClass: 使用したいエンジンコネクターのクラス。
戻り値 | 指定されたエンジンコネクターが利用可能な場合に true が返されます。
例外 | なし

名前 | getOtherEngineConnector
--- | ---
宣言形式 | <T> T getOtherEngineConnector(Class<T> engineConnectorClass)
機能 | 他種のエンジンコネクターを返します。 このメソッドを用いる際には、事前に、指定エンジンコネクターが利用可能である事を、 isOtherEngineConnectorAvailable(Class<?> engineConnectorClass) メソッドで確認する必要があります。
引数 | engineConnectorClass: 使用したいエンジンコネクターのクラス。
戻り値 | 指定された種類のエンジンコネクター。
例外 | ConnectorFatalException(非検査例外): 指定されたエンジンコネクターが利用不可能な場合にスローされます。