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

# External Namespace Connector Interface 1 (XNCI1)
インターフェース仕様書
(org.vcssl.connect.ExternalNamespaceConnectorInterface1)

## 概要

External Namespace Connector Interface 1 (XNCI1) は、 スクリプト内で使用可能な、複数の関数/変数をまとめて提供する、 名前空間プラグインを実装するためのインターフェースです。

## ステータス

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

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

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

## ライセンス

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

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

INTERFACE_TYPE_ID
  プラグインのロード時に参照される、このインターフェースの形式ID（値: "XNCI"）です。
INTERFACE_GENERATION
  このインターフェースの世代名です（値: "1"）。
String getNamespaceName()
  この名前空間の名称を取得します。
boolean isMandatoryToAccessMembers()
  この名前空間に属する関数/変数にアクセスする際に、名前空間の明示的な指定が必須であるかどうかを返します。
ExternalFunctionConnectorInterface1[] getFunctions()
  この名前空間に属する全ての関数を返します。
ExternalVariableConnectorInterface1[] getVariables()
  この名前空間に属する全ての変数を返します。
ExternalStructConnectorInterface1[] getStructs()
  この名前空間に属する全ての構造体を返します。
Class<?> getEngineConnectorClass()
  スクリプトエンジンと情報をやり取りする際に使用するオブジェクトである「エンジンコネクタ」の、 インターフェースまたはクラスを返します。
void preInitializeForConnection(Object engineConnector)
  このプラグインが、スクリプトエンジンに接続される際に必要となる初期化処理（関数/変数の初期化よりも前）を実行します。
void postInitializeForConnection(Object engineConnector)
  このプラグインが、スクリプトエンジンに接続される際に必要となる初期化処理（関数/変数の初期化よりも後）を実行します。
void preFinalizeForDisconnection(Object engineConnector)
  このプラグインが、スクリプトエンジンから接続解除される際に必要となる終了時処理（関数/変数の終了時処理よりも前）を実行します。
void postFinalizeForDisconnection(Object engineConnector)
  このプラグインが、スクリプトエンジンから接続解除される際に必要となる終了時処理（関数/変数の終了時処理よりも後）を実行します。
void preInitializeForExecution(Object engineConnector)
  スクリプトの実行毎に必要な初期化処理（関数/変数の初期化よりも前）を実行します。
void postInitializeForExecution(Object engineConnector)
  スクリプトの実行毎に必要な初期化処理（関数/変数の初期化よりも後）を実行します。
void preFinalizeForTermination(Object engineConnector)
  スクリプトの実行毎に必要な終了時処理（関数/変数の終了時処理よりも前）を実行します。
void postFinalizeForTermination(Object engineConnector)
  スクリプトの実行毎に必要な終了時処理（関数/変数の終了時処理よりも後）を実行します。

## フィールド

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

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

## メソッド

名前 | getNamespaceName
--- | ---
宣言形式 | String getNamespaceName()
機能 | この名前空間の名称を取得します。
引数 | なし
戻り値 | 名前空間の名称。
例外 | なし

名前 | isMandatoryToAccessMembers
--- | ---
宣言形式 | boolean isMandatoryToAccessMembers()
機能 | この名前空間に属する関数/変数にアクセスする際に、名前空間の明示的な指定が必須であるかどうかを返します。 この機能は、未対応の処理系においては無視される可能性があります。
引数 | なし
戻り値 | メンバーへのアクセスの際に、この名前空間の指定が必須である場合は true が返されます。
例外 | なし

名前 | getFunctions
--- | ---
宣言形式 | ExternalFunctionConnectorInterface1[] getFunctions()
機能 | この名前空間に属する全ての関数を返します。
引数 | なし
戻り値 | この名前空間に属する全ての関数を格納する配列。
例外 | なし

名前 | getVariables
--- | ---
宣言形式 | ExternalVariableConnectorInterface1[] getVariables()
機能 | この名前空間に属する全ての変数を返します。
引数 | なし
戻り値 | この名前空間に属する全ての変数を格納する配列。
例外 | なし

名前 | getVariables
--- | ---
宣言形式 | ExternalStructConnectorInterface1[] getStructs()
機能 | この名前空間に属する全ての構造体を返します。 ただし、ExternalStructConnectorInterface1 の仕様は現時点で完全に未定であり、 同名のインターフェースファイルが定義されているのみの段階です。 このメソッドも、現状では予約的に宣言されているのみであり、常に空配列を返します （プラグイン開発の際は、そのように実装します）。
引数 | なし
戻り値 | この名前空間に属する全ての構造体を格納する配列。
例外 | なし

名前 | getEngineConnectorClass
--- | ---
宣言形式 | Class<?> getEngineConnectorClass()
機能 | スクリプトエンジンと情報をやり取りする際に使用するオブジェクトである「エンジンコネクタ」の、 インターフェースまたはクラスを返します。 このメソッドで戻り値として指定したインターフェースまたはクラスの実装インスタンスが、 preInitializeForConnection(Object engineConnector) メソッド等の初期化/終了時メソッド群の、引数 engineConnector に渡されます。 利用可能なエンジンコネクタの形式は、スクリプトエンジンの実装に依存しますが、 少なくとも ECI1 は利用可能である事が、 XNCI1の仕様上保証されています。
引数 | なし
戻り値 | 使用したいエンジンコネクタのインターフェースまたはクラス。
例外 | なし

名前 | preInitializeForConnection
--- | ---
宣言形式 | void preInitializeForConnection(Object engineConnector) throws ConnectorException
機能 | このプラグインが、スクリプトエンジンに接続される際に必要となる初期化処理を実行します。 このインターフェースでは、接続初期化処理は 2 通り（pre- と post-）実装可能です。 こちらの処理（pre-）は、この名前空間に属する全ての変数/関数の接続初期化処理よりも前に実行されます。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 初期化処理に失敗した場合にスローされます。

名前 | postInitializeForConnection
--- | ---
宣言形式 | void postInitializeForConnection(Object engineConnector) throws ConnectorException
機能 | このプラグインが、スクリプトエンジンに接続される際に必要となる初期化処理を実行します。 このインターフェースでは、接続初期化処理は 2 通り（pre- と post-）実装可能です。 こちらの処理（post-）は、この名前空間に属する全ての変数/関数の接続初期化処理よりも後に実行されます。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 初期化処理に失敗した場合にスローされます。

名前 | preFinalizeForDisconnection
--- | ---
宣言形式 | void preFinalizeForDisconnection(Object engineConnector) throws ConnectorException
機能 | このプラグインが、スクリプトエンジンから接続解除される際に必要となる終了時処理を実行します。 このインターフェースでは、接続終了時処理は 2 通り（pre- と post-）実装可能です。 こちらの処理（pre-）は、この名前空間に属する全ての変数/関数の接続終了時処理よりも前に実行されます。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 終了時処理に失敗した場合にスローされます。

名前 | postFinalizeForDisconnection
--- | ---
宣言形式 | void postFinalizeForDisconnection(Object engineConnector) throws ConnectorException
機能 | このプラグインが、スクリプトエンジンから接続解除される際に必要となる終了時処理を実行します。 このインターフェースでは、接続終了時処理は 2 通り（pre- と post-）実装可能です。 こちらの処理（post-）は、この名前空間に属する全ての変数/関数の接続終了時処理よりも後に実行されます。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 終了時処理に失敗した場合にスローされます。

名前 | preInitializeForExecution
--- | ---
宣言形式 | void preInitializeForExecution(Object engineConnector) throws ConnectorException
機能 | スクリプトの実行毎に必要な初期化処理を実行します。 このインターフェースでは、実行毎初期化処理は 2 通り（pre- と post-）実装可能です。 こちらの処理（pre-）は、この名前空間に属する全ての変数/関数の実行毎初期化処理よりも前に実行されます。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 初期化処理に失敗した場合にスローされます。

名前 | postInitializeForExecution
--- | ---
宣言形式 | void postInitializeForExecution(Object engineConnector) throws ConnectorException
機能 | スクリプトの実行毎に必要な初期化処理を実行します。 このインターフェースでは、実行毎初期化処理は 2 通り（pre- と post-）実装可能です。 こちらの処理（post-）は、この名前空間に属する全ての変数/関数の実行毎初期化処理よりも後に実行されます。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 初期化処理に失敗した場合にスローされます。

名前 | preFinalizeForTermination
--- | ---
宣言形式 | void preFinalizeForTermination(Object engineConnector) throws ConnectorException
機能 | スクリプトの実行毎に必要な終了時処理を実行します。 このインターフェースでは、実行毎終了時処理は 2 通り（pre- と post-）実装可能です。 こちらの処理（pre-）は、この名前空間に属する全ての変数/関数の実行毎終了時処理よりも前に実行されます。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 終了時処理に失敗した場合にスローされます。

名前 | postFinalizeForTermination
--- | ---
宣言形式 | void postFinalizeForTermination(Object engineConnector) throws ConnectorException
機能 | スクリプトの実行毎に必要な終了時処理を実行します。 このインターフェースでは、実行毎終了時処理は 2 通り（pre- と post-）実装可能です。 こちらの処理（post-）は、この名前空間に属する全ての変数/関数の実行毎終了時処理よりも後に実行されます。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 終了時処理に失敗した場合にスローされます。