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

# External Function Connector Interface 1 (XFCI1)
インターフェース仕様書
(org.vcssl.connect.ExternalFunctionConnectorInterface1)

## 概要

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

## ステータス

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

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

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

## ライセンス

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

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

INTERFACE_TYPE_ID
  プラグインのロード時に参照される、このインターフェースの形式ID（値: "XFCI"）です。
INTERFACE_GENERATION
  このインターフェースの世代名です（値: "1"）。
String getFunctionName()
  関数名を取得します。
boolean hasParameterNames()
  引数名を取得可能かどうかを判定します。
String[] getParameterNames()
  全引数の名前を返します。
Class<?>[] getParameterClasses()
  全引数のデータ型と配列次元数を表す、Class クラスのインスタンスを返します。
Class<?>[] getParameterUnconvertedClasses()
  データ変換機能を無効化している場合において、 「 引数のデータのやり取りに用いるデータ入出力インターフェース 」の型を表す、 Class クラスのインスタンスを返します。
boolean[] getParameterDataTypeArbitrarinesses()
  全引数におけるデータ型の任意性を取得します。
boolean[] getParameterArrayRankArbitrarinesses()
  全引数における配列次元数の任意性を取得します。
boolean[] getParameterReferencenesses()
  全引数における参照性を取得します。
boolean[] getParameterConstantnesses()
  全引数における定数性を取得します。
boolean isParameterCountArbitrary()
  任意個の引数を受け取るかどうかを返します。
boolean hasVariadicParameters()
  （現在のVCSSL/Vnano処理系では未サポートの機能です。）
Class<?> getReturnClass(Class<?>[] parameterClasses)
  この関数の戻り値のデータ型と配列次元数を表す、 Class クラスのインスタンスを返します。
Class<?> getReturnUnconvertedClass(Class<?>[] parameterClasses)
  データ変換機能を無効化している場合において、 「 この関数の戻り値のデータのやり取りに用いる、データ入出力インターフェースの型 」 を表す、Class クラスのインスタンスを返します。
boolean isReturnDataTypeArbitrary()
  この関数の戻り値のデータ型が、任意に変化するかどうかを返します。
boolean isReturnArrayRankArbitrary()
  この関数の戻り値の配列次元数が、任意に変化するかどうかを返します。
boolean isDataConversionNecessary()
  この関数の引数や戻り値に対して、データ変換が必要かどうかを返します。
Object invoke(Object[] arguments)
  この関数の処理を実行します。
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

## メソッド

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

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

名前 | getParameterNames
--- | ---
宣言形式 | String[] getParameterNames()
機能 | 全引数の名前を返します。
引数 | なし
戻り値 | 全引数の名前を格納する配列。
例外 | なし

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

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

名前 | getParameterDataTypeArbitrarinesses
--- | ---
宣言形式 | boolean[] getParameterDataTypeArbitrarinesses()
機能 | 全引数におけるデータ型の任意性を取得します。 データ型の任意性として true が指定された引数に対しては、呼び出し時に任意の型の値を受け取れるようになります。
引数 | なし
戻り値 | 各要素が、各引数のデータ型の任意性を表す配列。
例外 | なし

名前 | getParameterArrayRankArbitrarinesses
--- | ---
宣言形式 | boolean[] getParameterArrayRankArbitrarinesses()
機能 | 全引数における配列次元数の任意性を取得します。 データ型の任意性として true が指定された引数に対しては、呼び出し時に任意次元の配列を受け取れるようになります。
引数 | なし
戻り値 | 各要素が、各引数の配列次元数の任意性を表す配列。
例外 | なし

名前 | getParameterReferencenesses
--- | ---
宣言形式 | boolean[] getParameterReferencenesses()
機能 | 全引数における参照性を取得します。 参照性として true が指定された引数に対しては、呼び出し時に実引数が参照渡しされます。
引数 | なし
戻り値 | 各要素が、各引数の参照性を表す配列。
例外 | なし

名前 | getParameterConstantnesses
--- | ---
宣言形式 | boolean[] getParameterConstantnesses()
機能 | 全引数における定数性を取得します。 定数性として true が指定された引数に対しては、この関数の実行時に、実引数の値が変更されないものと見なされます。
引数 | なし
戻り値 | 各要素が、各引数の定数性を表す配列。
例外 | なし

名前 | isParameterCountArbitrary
--- | ---
宣言形式 | boolean isParameterCountArbitrary()
機能 | 任意個の引数を受け取るかどうかを返します。 この機能が有効化されている（このメソッドが true を返す）場合、 デフォルトでは、全引数のデータ型と配列次元数は同一であると見なされます。 従ってその場合、getParameterClasses() メソッドは要素数 1 の配列を返すようにし、 その値が、全引数のデータ型と配列次元数を表すものと見なされます。 ただし、 getParameterDataTypeArbitrarinesses() メソッドや getParameterArrayRankArbitrarinesses() メソッドが { true } を返す場合には、データ型や配列次元数は任意となるため、各引数で異なる場合も生じ得ます.
引数 | なし
戻り値 | この関数が任意個の引数を取る場合に true が返されます。
例外 | なし

名前 | hasVariadicParameters
--- | ---
宣言形式 | boolean hasVariadicParameters()
機能 | （現在のVCSSL/Vnano処理系では未サポートの機能です。）
引数 | なし
戻り値 | （現在のVCSSL/Vnano処理系では未サポートの機能です。）
例外 | なし

名前 | getReturnClass
--- | ---
宣言形式 | Class<?> getReturnClass(Class<?>[] parameterClasses)
機能 | この関数の戻り値のデータ型と配列次元数を表す、 Class クラスのインスタンスを返します。 例えば、double 型の戻り値に対しては double.class を返し、long[][] 型の戻り値に対しては long[][].class を返します。 （※ プラグインでは、スクリプト内での float 型は double 型、スクリプト内での int 型は long 型として扱います。）
引数 | parameterClasses: 各要素が各実引数のデータ型と配列次元数を表す、Class 型の配列。
戻り値 | この関数の戻り値におけるデータ型と配列次元数を表す、Class 型の値
例外 | なし

名前 | getReturnUnconvertedClass
--- | ---
宣言形式 | Class<?> getReturnUnconvertedClass(Class<?>[] parameterClasses)
機能 | データ変換機能 を無効化している場合において、 「 この関数の戻り値のデータのやり取りに用いる、データ入出力インターフェースの型 」 を表す、Class クラスのインスタンスを返します。 スカラの戻り値に対する入出力インターフェースとしては、 Int64 SDAI1、 Float64 SDAI1、 Bool SDAI1、 String SDAI1、 および ADAI1 が利用可能です。 配列の戻り値に対しては、 ADAI1 のみが利用可能です。 なお、引数 parameterClasses には、スクリプト内での呼び出しにおける、引数のデータ型情報が渡されます. これにより、引数の型によって戻り値の型が異なるだけの、複数の関数に相当する処理を、まとめて提供する事ができます。 （そのような関数を実装する場合、併せて isReturnDataTypeArbitrary() および isReturnArrayRankArbitrary() メソッドが true を返すように実装する事で、戻り値のデータ型と配列次元数を「任意」に設定しておく必要があります。）
引数 | parameterClasses: 各要素が、各実引数のデータ型と配列次元数を表す、Class 型の配列。
戻り値 | 「戻り値のデータのやり取りに用いる、データ入出力インターフェースの型」を表す、Class 型のインスタンス
例外 | なし

名前 | isReturnDataTypeArbitrary
--- | ---
宣言形式 | boolean isReturnDataTypeArbitrary()
機能 | この関数の戻り値のデータ型が、任意に変化するかどうかを返します。 この機能は、戻り値の型が引数の型に依存するような、一種のジェネリックな関数を実装するためのものです。 従って、この機能を有効化した場合（このメソッドが true を返す場合）でも、 渡される引数のデータ型が確定すると、それに応じて戻り値の型も一意に決定される必要があります。 getReturnClass(Class[]) メソッドの説明も併せてご参照ください。
引数 | なし
戻り値 | 戻り値のデータ型が、任意に変化する場合に true を返します。
例外 | なし

名前 | isReturnArrayRankArbitrary
--- | ---
宣言形式 | boolean isReturnArrayRankArbitrary()
機能 | この関数の戻り値の配列次元数が、任意に変化するかどうかを返します。 この機能は、戻り値の配列次元数が引数の型/次元数に依存するような、一種のジェネリックな関数を実装するためのものです。 従って、この機能を有効化した場合（このメソッドが true を返す場合）でも、 渡される引数のデータ型/次元数が確定すると、それに応じて戻り値の次元数も一意に決定される必要があります。 getReturnClass(Class[]) メソッドの説明も併せてご参照ください。
引数 | なし
戻り値 | 戻り値の配列次元数が、任意に変化する場合に true を返します。
例外 | なし

名前 | isDataConversionNecessary
--- | ---
宣言形式 | boolean isDataConversionNecessary()
機能 | この関数の引数や戻り値に対して、データ変換が必要かどうかを返します。 この機能が有効化されている（このメソッドが true を返すようにした）場合、 各引数のデータを、単純なデータ型で受け取る事ができます。例えば、 double 型引数においては Double 型インスタンス、long[][] 型引数に対しては long[][] 型インスタンスなど受け取れます。 戻り値に対しても、引数と同様に、単純なデータ型の値で返す事ができます。 一方、この機能が無効化されている（このメソッドが false を返すようにした）場合、 引数や戻り値のデータに対しては、各種のデータ入出力インターフェースを介してアクセスする必要があります。 その際、使用するデータ入出力インターフェースは getParameterUnconvertedClasses() メソッドや getReturnUnconvertedClass(Class[]) メソッドの戻り値として指定します。 この機能は、有効化した方がプラグインの実装が単純になりますが、 反面、引数や戻り値のやり取りにおいて、データ変換処理のオーバーヘッドがかかるようになります。 従って、処理速度が要求される処理において、頻繁に呼び出されるような関数プラグインの実装においては、 この機能を無効化する事で、呼び出しコストを削減できる利点があります。
引数 | なし
戻り値 | データ変換が必要なら true を返します。
例外 | なし

名前 | invoke
--- | ---
宣言形式 | Object invoke(Object[] arguments) throws ConnectorException
機能 | この関数の処理を実行します。 関数呼び出し時の実引数のデータは、このメソッドの引数 arguments に渡されます。 この arguments は Object[] 型の配列で、各要素に各実引数のデータが格納されます。 データ変換機能が有効化されている場合（isDataConversionNecessary() メソッド参照）、 各実引数は単純な型のデータとして arguments に格納されます。例えば、 double 型引数に対しては Double インスタンス、long[][] 型引数に対しては long[][] 型インスタンスなどです。 一方で、データ変換機能が無効化されている場合、arguments の各要素には、 各種のデータ入出力インターフェースを実装したデータコンテナオブジェクトが格納されて渡されます。 それを介して、各引数のデータにアクセスします。 具体的なデータ入出力インターフェースは getParameterUnconvertedClasses() メソッドの戻り値として指定します。 なお、この場合、arguments[0] には、戻り値のデータを格納するためのデータコンテナオブジェクトが割り当てられています。 従って最初の引数は arguments[1]、次の引数は arguments[2]、... を参照する必要があります。
引数 | arguments: 関数呼び出し時における、全ての実引数を格納する配列。
戻り値 | 関数呼び出しにおける戻り値。 （データ変換機能が無効化されている場合は、代わりに arguments[0] に戻り値を格納します。）
例外 | ConnectorException: 関数の実行処理において, 何らかのエラーが発生した場合にスローされます。

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

名前 | 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: 終了時処理に失敗した場合にスローされます。