External Variable Connector Interface 1 (XVCI1) is an interface for implementing external variable plug-ins which provide variables 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: "XVCI") 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 | getVariableName |
|---|---|
| Signature | String getVariableName() |
| Description | Gets the name of this variable. |
| Parameters | None |
| Return | The name of this variable. |
| Exception | None |
| Name | getDataClass |
|---|---|
| Signature | Class<?> getDataClass() |
| Description |
Returns the instance of "Class" class representing the data-type and the array-rank of this variable. For example, returns double.class for double-type ("float" in scripts) variable, and returns long[][].class for long[][]-type ("int[][]" in scripts) variable. |
| Parameters | None |
| Return | The Class representing the data-type and the array-rank of this variable. |
| Exception | None |
| Name | getDataUnconvertedClass |
|---|---|
| Signature | Class<?> getDataUnconvertedClass() |
| Description |
Returns the instance of "Class" class representing data-I/O interfaces for accessing to data of this variable, when the data-conversion feature is disabled. As interfaces for accessing to data of a scalar variable, Int64 SDAI1、 Float64 SDAI1、 Bool SDAI1、 String SDAI1、 and ADAI1 are available. For an array variable, only ADAI1 is available for accessing to data. |
| Parameters | None |
| Return | The Class representing the I/O interface for accessing to the data of this variable. |
| Exception | None |
| Name | isConstant |
|---|---|
| Signature | boolean isConstant() |
| Description | Returns whether this variable is a constant. |
| Parameters | None |
| Return | Returns true if this variable is a constant. |
| Exception | None |
| Name | isReference |
|---|---|
| Signature | boolean isReference() |
| Description | (Unsupported feature on the current version of VCSSL/Vnano Engine) Returns whether this variable is a reference. |
| Parameters | None |
| Return | Returns true if this variable is a reference. |
| Exception | None |
| Name | isDataTypeArbitrary |
|---|---|
| Signature | boolean isDataTypeArbitrary() |
| Description | (Unsupported feature on the current version of VCSSL/Vnano Engine) Returns whether the data-type of this variable varies arbitrary. |
| Parameters | None |
| Return | @return Returns true if the data-type of this variable varies arbitrary. |
| Exception | None |
| Name | isArrayRankArbitrary |
|---|---|
| Signature | boolean isArrayRankArbitrary() |
| Description | (Unsupported feature on the current version of VCSSL/Vnano Engine) Returns whether the array-rank of this variable varies arbitrary. |
| Parameters | None |
| Return | Returns true if the array-rank of this variable varies arbitrary. |
| Exception | None |
| Name | isDataConversionNecessary |
|---|---|
| Signature | boolean isDataConversionNecessary() |
| Description |
Returns whether the data-conversions for accessing data of this variable is necessary. When this feature is enabled (when this method returns "true"), you can set/get data of this variable by using simple data-types. For example, you can get/set Double instance for double-type ("float" in scripts) variable, long[][] instance for long[][]-type ("int[][]" in scripts) variable, and so on. On the other hand, when this feature is disabled (when this method retunrs "false"), it is necessary to access to data through a data-I/O interface, of which type is specified as a return values of {@link getDataUnconvertedClass()} method. As interfaces for accessing to data of a scalar variable, Int64 SDAI1、 Float64 SDAI1、 Bool SDAI1、 String SDAI1、 and ADAI1 are available. For an array variable, only ADAI1 is available for accessing to data. |
| Parameters | None |
| Return | Returns true if the data-conversions are necessary. |
| Exception | None |
| Name | getData |
|---|---|
| Signature | Object getData() throws ConnectorException |
| Description |
Returns the data of this variable. This method is used when the data-conversion feature is enabled (when isDataConversionNecessary() returns false). |
| Parameters | None |
| Return | The data of this variable. |
| Exception | ConnectorException: Thrown when failed to access to the data. |
| Name | getData |
|---|---|
| Signature | void getData(Object dataContainer) throws ConnectorException |
| Description |
Gets the data of this variable through the argument. This method is used when the data-conversion feature is disabled (when isDataConversionNecessary() returns true). |
| Parameters | None |
| Return | The data container object for storing the data to be gotten. |
| Exception | ConnectorException: Thrown when failed to access to the data. |
| Name | setData |
|---|---|
| Signature | void setData(Object data) throws ConnectorException |
| Description | Sets the data of this variable. |
| Parameters | data: The data of this variable to be set. |
| Return | None |
| Exception | ConnectorException: Thrown when failed to access to the data. |
| 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 XVCI1. |
| 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. |