VCSSL/VNANO PLUGIN INTERFACE SPECIFICATION

# External Variable Connector Interface 1 (XVCI1)
Specification Document
(org.vcssl.connect.ExternalVariableConnectorInterface1)

## Abstract

External Variable Connector Interface 1 (XVCI1) is an interface for implementing external variable plug-ins which provide variables available in scripts.

## Status

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.

## License

This interface is published under CC0, which is almost the same as the so-called "copyright-free" (domain).

## List of Fields/Methods

INTERFACE_TYPE_ID
  The type ID of this interface (value: "XVCI") referred when the plug-in will be loaded.
INTERFACE_GENERATION
  The generation of this interface (value: "1").
String getVariableName()
  Gets the name of the variable.
Class<?> getDataClass()
  Returns the instance of "Class" class representing the data-type and the array-rank of this variable.
Class<?> getDataUnconvertedClass()
  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.
boolean isConstant()
  Returns whether this variable is a constant.
boolean isReference()
  （Unsupported feature on the current version of VCSSL/Vnano Engine）Returns whether this variable is a reference.
boolean isDataTypeArbitrary()
  (Unsupported feature on the current version of VCSSL/Vnano Engine) Returns whether the data-type of this variable varies arbitrary.
boolean isArrayRankArbitrary()
  (Unsupported feature on the current version of VCSSL/Vnano Engine) Returns whether the array-rank of this variable varies arbitrary.
boolean isDataConversionNecessary()
  Returns whether the data-conversions for accessing data of this variable is necessary.
Object getData()
  Returns the data of this variable.
void getData(Object dataContainer)
  Gets the data of this variable through the argument.
void setData(Object data)
  Sets the data of this variable.
Class<?> getEngineConnectorClass()
  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.
void initializeForConnection(Object engineConnector)
  Performs the initialization process necessary when this plug-in is connected to the scripting engine.
void finalizeForDisconnection(Object engineConnector)
  Performs the finalization process necessary when this plug-in is disconnected from the scripting engine.
void initializeForExecution(Object engineConnector)
  Performs the initialization process necessary for each execution of a script.
void finalizeForTermination(Object engineConnector)
  Performs the finalization process necessary for each execution of a script.

## Fields

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

## Methods

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.