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

# External Variable Connector Interface 1 (XVCI1)
インターフェース仕様書
(org.vcssl.connect.ExternalVariableConnectorInterface1)

## 概要

External Variable Connector Interface 1 (XVCI1) は、 スクリプト内で使用可能な変数を提供する、外部変数プラグインを実装するためのインターフェースです。

## ステータス

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

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

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

## ライセンス

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

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

INTERFACE_TYPE_ID
  プラグインのロード時に参照される、このインターフェースの形式ID（値: "XVCI"）です。
INTERFACE_GENERATION
  このインターフェースの世代名です（値: "1"）。
String getVariableName()
  変数名を取得します。
Class<?> getDataClass()
  この変数のデータ型と配列次元数を表す Class インスタンスを返します。
Class<?> getDataUnconvertedClass()
  データ変換機能を無効化している場合において、変数のデータの読み書きに用いる、データ入出力インターフェースの型を表す Class インスタンスを返します。
boolean isConstant()
  この変数が定数であるかどうかを取得します。
boolean isReference()
  （現在のVCSSL/Vnano処理系では未サポート）この変数が参照であるかどうかを取得します。
boolean isDataTypeArbitrary()
  （現在のVCSSL/Vnano処理系では未サポート）この変数のデータ型が、任意に変化するかどうかを取得します。
boolean isArrayRankArbitrary()
  （現在のVCSSL/Vnano処理系では未サポート）この変数の配列次元数が、任意に変化するかどうかを取得します。
boolean isDataConversionNecessary()
  この変数の値の読み書きに際して、データ型の変換が必要かどうかを取得します。
Object getData()
  この変数のデータを返します。
void getData(Object dataContainer)
  引数を介して、この変数のデータを取得します。
void setData(Object data)
  この変数のデータを設定します。
Class<?> getEngineConnectorClass()
  スクリプトエンジンと情報をやり取りする際に使用するオブジェクトである「エンジンコネクタ」の、インターフェースまたはクラスを返します。
void initializeForConnection(Object engineConnector)
  このプラグインが、スクリプトエンジンに接続される際に必要となる初期化処理を実行します。
void finalizeForDisconnection(Object engineConnector)
  このプラグインが、スクリプトエンジンから接続解除される際に必要となる終了時処理を実行します。
void initializeForExecution(Object engineConnector)
  スクリプトの実行毎に必要な初期化処理を実行します。
void finalizeForTermination(Object engineConnector)
  スクリプトの実行毎に必要な終了時処理を実行します。

## フィールド

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

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

## メソッド

名前 | getVariableName
--- | ---
宣言形式 | String getVariableName()
機能 | 変数名を取得します。
引数 | なし
戻り値 | 変数名。
例外 | なし

名前 | getDataClass
--- | ---
宣言形式 | Class<?> getDataClass()
機能 | この変数のデータ型と配列次元数を表す Class インスタンスを返します。 例えば, データが double 型（スクリプト内では float 型）の変数の場合は double.class を、 long[][] 型（スクリプト内では int[][] 型）の場合には long[][].class を返します。
引数 | なし
戻り値 | この変数のデータ型と配列次元数を表す Class インスタンス。
例外 | なし

名前 | getDataUnconvertedClass
--- | ---
宣言形式 | Class<?> getDataUnconvertedClass()
機能 | データ変換機能 を無効化している場合において、変数のデータの読み書きに用いる、データ入出力インターフェースの型を表す Class インスタンスを返します。 スカラの変数に対する入出力インターフェースとしては、 Int64 SDAI1、 Float64 SDAI1、 Bool SDAI1、 String SDAI1、 および ADAI1 が利用可能です。 配列変数に対しては、 ADAI1 のみが利用可能です。
引数 | なし
戻り値 | この変数のデータの読み書きに使用する、データ入出力インターフェースの型を表す Class インスタンス。
例外 | なし

名前 | isConstant
--- | ---
宣言形式 | boolean isConstant()
機能 | この変数が定数であるかどうかを取得します。
引数 | なし
戻り値 | この変数が定数でれば true を返します。
例外 | なし

名前 | isReference
--- | ---
宣言形式 | boolean isReference()
機能 | （現在のVCSSL/Vnano処理系では未サポート）この変数が参照であるかどうかを取得します。
引数 | なし
戻り値 | この変数が参照である場合に true を返します。
例外 | なし

名前 | isDataTypeArbitrary
--- | ---
宣言形式 | boolean isDataTypeArbitrary()
機能 | （現在のVCSSL/Vnano処理系では未サポート）この変数のデータ型が、任意に変化するかどうかを取得します。
引数 | なし
戻り値 | この変数のデータ型が任意に変化する場合に true が返されます。
例外 | なし

名前 | isArrayRankArbitrary
--- | ---
宣言形式 | boolean isArrayRankArbitrary()
機能 | （現在のVCSSL/Vnano処理系では未サポート）この変数の配列次元数が、任意に変化するかどうかを取得します。
引数 | なし
戻り値 | この変数の配列次元数が任意に変化する場合に true を返します。
例外 | なし

名前 | isDataConversionNecessary
--- | ---
宣言形式 | boolean isDataConversionNecessary()
機能 | この変数の値の読み書きに際して、データ型の変換が必要かどうかを取得します。 この機能が有効化されている（このメソッドが true を返すようにした）場合、 変数のデータを、単純なデータ型で読み書きする事ができます。例えば、 double 型（スクリプト内では float 型）変数のデータにおいては Double 型インスタンス、 long[][] 型（スクリプト内では int[][] 型）変数データに対しては long[][] 型インスタンス などとして読み書きできます。 一方、この機能が無効化されている（このメソッドが false を返すようにした）場合、 変数のデータに対しては、各種のデータ入出力インターフェースを介してアクセスする必要があります。 その際、使用するデータ入出力インターフェースは、 getDataUnconvertedClass() メソッドの戻り値として指定します。 スカラの変数に対する入出力インターフェースとしては、 Int64 SDAI1、 Float64 SDAI1、 Bool SDAI1、 String SDAI1、 および ADAI1 が利用可能です。 配列変数に対しては、 ADAI1 のみが利用可能です。
引数 | なし
戻り値 | データ変換が必要なら true を返します。
例外 | なし

名前 | getData
--- | ---
宣言形式 | Object getData() throws ConnectorException
機能 | この変数のデータを返します。 このメソッドは、データ変換機能が無効化されている場合 （isDataConversionNecessary() メソッドが false を返す場合） に使用されます。
引数 | なし
戻り値 | この変数のデータ。
例外 | ConnectorException: データへのアクセスに失敗した場合にスローされます。

名前 | getData
--- | ---
宣言形式 | void getData(Object dataContainer) throws ConnectorException
機能 | 引数を介して、この変数のデータを取得します。 このメソッドは、データ変換機能が無効化されている場合 （isDataConversionNecessary() メソッドが false を返す場合） に使用されます。
引数 | なし
戻り値 | この変数のデータ。
例外 | ConnectorException: データへのアクセスに失敗した場合にスローされます。

名前 | setData
--- | ---
宣言形式 | void setData(Object data) throws ConnectorException
機能 | この変数のデータを設定します。
引数 | data: この変数に設定するデータ。
戻り値 | なし
例外 | ConnectorException: データへのアクセスに失敗した場合にスローされます。

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

名前 | initializeForConnection
--- | ---
宣言形式 | void initializeForConnection(Object engineConnector) throws ConnectorException
機能 | このプラグインが、スクリプトエンジンに接続される際に必要となる初期化処理を実行します。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 初期化処理に失敗した場合にスローされます。

名前 | finalizeForDisconnection
--- | ---
宣言形式 | void finalizeForDisconnection(Object engineConnector) throws ConnectorException
機能 | このプラグインが、スクリプトエンジンから接続解除される際に必要となる終了時処理を実行します。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 終了時処理に失敗した場合にスローされます。

名前 | initializeForExecution
--- | ---
宣言形式 | void initializeForExecution(Object engineConnector) throws ConnectorException
機能 | スクリプトの実行毎に必要な初期化処理を実行します。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 初期化処理に失敗した場合にスローされます。

名前 | finalizeForTermination
--- | ---
宣言形式 | void finalizeForTermination(Object engineConnector) throws ConnectorException
機能 | スクリプトの実行毎に必要な終了時処理を実行します。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 終了時処理に失敗した場合にスローされます。