External Function Connector Interface 1 (XFCI1) is an interface for implementing external function plug-ins which provide functions available in scripts.
The status of this interface is "FINALIZED".
The specification of this interface had been finalized at 2022/08/31. No modifications will be applied for this interface, excluding documents/comments.
This interface is currently supported by the scripting engine of Vnano. You can use this interface for development of plug-ins of applications equipped with the Vnano engine.
This interface is published under CC0, which is almost the same as the so-called "copyright-free" (domain).
| Name | INTERFACE_TYPE_ID |
|---|---|
| Value | The type ID of this interface (value: "XFCI") referred when the plug-in will be loaded. |
| Type | static final String |
| Name | INTERFACE_GENERATION |
|---|---|
| Value | The generation of this interface (value: "1"). |
| Type | static final String |
| Name | getFunctionName |
|---|---|
| Signature | String getFunctionName() |
| Description | Gets the name of the function. |
| Parameters | None |
| Return | The name of the function. |
| Exception | None |
| Name | hasParameterNames |
|---|---|
| Signature | boolean hasParameterNames() |
| Description | Returns whether parameter names can be gotten. |
| Parameters | None |
| Return | Returns true if parameter names can be gotten. |
| Exception | None |
| Name | getParameterNames |
|---|---|
| Signature | String[] getParameterNames() |
| Description | Returns names of all parameters. |
| Parameters | None |
| Return | The array storing names of all parameters. |
| Exception | None |
| Name | getParameterClasses |
|---|---|
| Signature | Class<?>[] getParameterClasses() |
| Description |
Returns the instances of "Class" class representing data-types and array-ranks of all parameters.
For example, returns { double.class, long[][].class } when parameters of this function are: (double, long[][]).
|
| Parameters | None |
| Return | The "Class" type array, each element represents the data-type and array-rank of each parameter. |
| Exception | None |
| Name | getParameterUnconvertedClasses |
|---|---|
| Signature | Class<?>[] getParameterUnconvertedClasses() |
| Description |
Returns the instance of "Class" class representing data-I/O interfaces for accessing to data of parameters, when the data-conversion feature is disabled. As interfaces for accessing to a scalar parameter, Int64 SDAI1、 Float64 SDAI1、 Bool SDAI1、 String SDAI1、 and ADAI1 are available. For an array parameter, only ADAI1 is available. |
| Parameters | None |
| Return | The "Class" type array, each element represents the I/O interface for accessing to the data of each parameter. |
| Exception | None |
| Name | getParameterDataTypeArbitrarinesses |
|---|---|
| Signature | boolean[] getParameterDataTypeArbitrarinesses() |
| Description |
Returns arbitrarinesses of data-types of parameters. When the data-type arbitrariness is "true" for a parameter, any type of value can be passed as an actual argument for the parameter. |
| Parameters | None |
| Return |
The array storing data-type arbitrarinesses of all parameters.
(Each element represents the data-type arbitrariness of each paremeter.) |
| Exception | None |
| Name | getParameterArrayRankArbitrarinesses |
|---|---|
| Signature | boolean[] getParameterArrayRankArbitrarinesses() |
| Description |
Returns arbitrarinesses of array-ranks of parameters. When the array-rank arbitrariness is "true" for a parameter, an array having any rank (number of dimensions) can be passed as an actual argument for the parameter. |
| Parameters | None |
| Return |
The array storing array-rank arbitrarinesses of all parameters.
(Each element represents the array-rank arbitrariness of each paremeter.) |
| Exception | None |
| Name | getParameterReferencenesses |
|---|---|
| Signature | boolean[] getParameterReferencenesses() |
| Description |
Returns referencenesses of parameters. When the referenceness is "true" for a parameter, an actual argument of the parameter will be passed by reference. |
| Parameters | None |
| Return |
The array storing referencenesses of all parameters.
(Each element represents the referenceness of each paremeter.) |
| Exception | None |
| Name | getParameterConstantnesses |
|---|---|
| Signature | boolean[] getParameterConstantnesses() |
| Description |
Returns constantnesses of parameters. When the constantness is "true" for a parameter, it is regarded that the value of an actual argument of the parameter will not be modified in the process of this function. |
| Parameters | None |
| Return |
The array storing constantnesses of all parameters.
(Each element represents the constantness of each paremeter.) |
| Exception | None |
| Name | isParameterCountArbitrary |
|---|---|
| Signature | boolean isParameterCountArbitrary() |
| Description |
Returns whether the number of parameters is arbitrary. When this feature is enabled (when this method returns "true"), by default, it is regarded that all parameters have the same data-type and array-rank. Hence, getParameterClasses() method should return an array of which length is 1, and it represents the data-type/array-rank of all parameters. However, if getParameterDataTypeArbitrarinesses() method or getParameterArrayRankArbitrarinesses() method returns { true }, data-types / array-ranks of parameters are arbitrary, so they may different each other. |
| Parameters | None |
| Return | Returns true if the number of parameters is arbitrary. |
| Exception | None |
| Name | hasVariadicParameters |
|---|---|
| Signature | boolean hasVariadicParameters() |
| Description | （Unsupported feature on the current version of VCSSL/Vnano Engine） |
| Parameters | None |
| Return | （Unsupported feature on the current version of VCSSL/Vnano Engine） |
| Exception | None |
| Name | getReturnClass |
|---|---|
| Signature | Class<?> getReturnClass(Class<?>[] parameterClasses) |
| Description |
Returns the instance of "Class" class, representing a data-type and an array-rank of the return value of this function.
For example, returns double.class for double-type return value,
returns long[][].class for long[][]-type return value, and so on.
|
| Parameters | parameterClasses: The "Class" type array, each element represents the data-type and array-rank of each actual argument. |
| Return | The "Class" type value representing the data-type and the array-rank of the return value of this function. |
| Exception | None |
| Name | getReturnUnconvertedClass |
|---|---|
| Signature | Class<?> getReturnUnconvertedClass(Class<?>[] parameterClasses) |
| Description |
Returns Class-instances representing data-I/O interfaces for accessing to data of return value of this function, when the data-conversion feature is disabled. As interfaces for accessing to a scalar return value, Int64 SDAI1、 Float64 SDAI1、 Bool SDAI1、 String SDAI1、 and ADAI1 are available. For an array return value, only ADAI1 is available. Also, information of data-types and array-ranks of actual arguments will be passed to "parameterClasses". The above information enable to implement a kind of "generic" function of which the data-type/array-rank varies depending on data-types/array-ranks of parameters. (To implement such functions, set the data-type/array-rank of the return value arbitrary, by implementing isReturnDataTypeArbitrary() and isReturnArrayRankArbitrary() methods to return "true".) |
| Parameters | parameterClasses: The "Class" type array, each element represents the data-type/array-rank of each actual argument. |
| Return | The "Class" type value representing the I/O interface for accessing to the data of return value. |
| Exception | None |
| Name | isReturnDataTypeArbitrary |
|---|---|
| Signature | boolean isReturnDataTypeArbitrary() |
| Description |
Returns whether the data-type of the return value of this function varies arbitrary. This feature is for implementing a kind of "generic" function of which type of return value varies depending on types of actual arguments. Hence, even if this feature is enabled (even if this method returns "true"), the type of the return value must be determined at when types of actual arguments are determined. See also: exprenation of getReturnClass(Class[]) method. |
| Parameters | None |
| Return | Returns true if the data-type of the return value varies arbitrary. |
| Exception | None |
| Name | isReturnArrayRankArbitrary |
|---|---|
| Signature | boolean isReturnArrayRankArbitrary() |
| Description |
Returns whether the array-rank (number of dimensions) of the return value of this function varies arbitrary. This feature is for implementing a kind of "generic" function of which array-rank of return value varies depending on types/ranks of actual arguments. Hence, even if this feature is enabled (even if this method returns "true"), the rank of the return value must be determined at when types/ranks of actual arguments are determined. See also: exprenation of getReturnClass(Class[]) method. |
| Parameters | None |
| Return | Returns true if the array-rank of the return value varies arbitrary. |
| Exception | None |
| Name | isDataConversionNecessary |
|---|---|
| Signature | boolean isDataConversionNecessary() |
| Description |
Returns whether the data-conversions for arguments and return value are necessary. When this feature is enabled (when this method returns "true"), you can receive data of arguments by using simple data-types. For example, you can receive Double instance for double-type parameter, long[][] instance for long[][]-type parameter, and so on. Also, as same as the arguments, you can return the simple data-type value as the return value of the function. On the other hand, when this feature is disabled (when this method retunrs "false"), it is necessary to access to data of parameters and the return value through data-I/O interfaces, which are specified as return values of getParameterUnconvertedClasses() and getReturnUnconvertedClass(Class[]) method. Enabling this feature make the implementation of the plugin simple. However, this feature takes overhead processing costs for converting data of parameters and return value. Therefore, if you want to implement a function plug-in which will be called frequently from scripts of which processing speed is required to be fast in some degree, disabling this feature gives some advantage to reduce overhead processing costs of function calls. |
| Parameters | None |
| Return | Returns true if the data-conversions are necessary. |
| Exception | None |
| Name | invoke |
|---|---|
| Signature | Object invoke(Object[] arguments) throws ConnectorException |
| Description |
Invokes the process of this function. The data of the actual arguments of the function will be passed to the argument of this method: "arguments", which is an Object[] type array storing data of each actual argument as an element. When data-conversion feature is enabled (see: {@link isDataConversionNecessary()} method), each actual argument will be stored as a simple type of data in "arguments". For example, Double instance for double-type parameter, long[][] instance for long[][]-type parameter, and so on. On the other hand, when data-conversion feature is disabled, in "arguments", each actual argument will be stored as a data-container object implementing data-I/O interface, specified as each element of return values of getParameterUnconvertedClasses() method. In addition, in this case, "arguments[0]" will be a data-container object for storing data of the return value of this function, so the data of first argument will be stored at "arguments[1]", and the next arg will be stored at "argument[2]". |
| Parameters | arguments: The array storing all actual arguments, which are passed from the caller-side. |
| Return |
The return value of the function call.
(When the data conversion feature is disabled, store the return value to arguments[0] instead.) |
| Exception | ConnectorException: Thrown when any error occurred in the process of this function. |
| Name | getEngineConnectorClass |
|---|---|
| Signature | Class<?> getEngineConnectorClass() |
| Description |
Returns the instance of "Class" class, representing the interface or the class of the engine connector, which is an object for communicating with the scripting engine. The instance of the specified interface/class by this method will be passed to the argument of initialization/finalization methods, e.g.: initializeForConnection(Object engineConnector). What type of interfaces are available depend on the implementation of the scripting engine, but at least, ECI1 is guaranteed to be available by the specification of XFCI1. |
| Parameters | None |
| Return | The Class representing the interface/class for communicating with the scripting engine. |
| Exception | None |
| Name | initializeForConnection |
|---|---|
| Signature | void initializeForConnection(Object engineConnector) throws ConnectorException |
| Description | Performs the initialization process necessary when this plug-in is connected to the scripting engine. |
| Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method). |
| Return | None |
| Exception | ConnectorException: Thrown when the initialization has failed. |
| Name | finalizeForDisconnection |
|---|---|
| Signature | void finalizeForDisconnection(Object engineConnector) throws ConnectorException |
| Description | Performs the finalization process necessary when this plug-in is disconnected from the scripting engine. |
| Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method). |
| Return | None |
| Exception | ConnectorException: Thrown when the finalization has failed. |
| Name | initializeForExecution |
|---|---|
| Signature | void initializeForExecution(Object engineConnector) throws ConnectorException |
| Description | Performs the initialization process necessary for each execution of a script. |
| Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method). |
| Return | None |
| Exception | ConnectorException: Thrown when the initialization has failed. |
| Name | finalizeForTermination |
|---|---|
| Signature | void finalizeForTermination(Object engineConnector) throws ConnectorException |
| Description | Performs the finalization process necessary for each execution of a script. |
| Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method). |
| Return | None |
| Exception | ConnectorException: Thrown when the finalization has failed. |