VCSSL/VNANO PLUGIN INTERFACE SPECIFICATION

# External Namespace Connector Interface 1 (XNCI1)
Specification Document
(org.vcssl.connect.ExternalNamespaceConnectorInterface1)

## Abstract

External Namespace Connector Interface 1 (XNCI1) is an interface (abbreviated as XNCI1) for implementing namespace plug-ins which provides multiple functions and 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: "XNCI") referred when the plug-in will be loaded.
INTERFACE_GENERATION
  The generation of this interface (value: "1").
String getNamespaceName()
  Gets the name of this namespace.
boolean isMandatoryToAccessMembers()
  Returns whether it is mandatory to specify of this namespace explicitly when accessing member functions/variables.
ExternalFunctionConnectorInterface1[] getFunctions()
  Gets all functions belong to this namespace.
ExternalVariableConnectorInterface1[] getVariables()
  Gets all variables belong to this namespace.
ExternalStructConnectorInterface1[] getStructs()
  Gets all structs belong to this namespace.
Class<?> getEngineConnectorClass()
  Gets 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 preInitializeForConnection(Object engineConnector)
  Performs the pre-initialization process necessary when this plug-in is connected to the script engine.
void postInitializeForConnection(Object engineConnector)
  Performs the post-initialization process necessary when this plug-in is connected to the script engine.
void preFinalizeForDisconnection(Object engineConnector)
  Performs the pre-finalization process necessary when this plug-in is disconnected from the script engine.
void postFinalizeForDisconnection(Object engineConnector)
  Performs the post-finalization process necessary when this plug-in is disconnected from the script engine.
void preInitializeForExecution(Object engineConnector)
  Performs the pre-initialization process necessary for each execution of a script.
void postInitializeForExecution(Object engineConnector)
  Performs the post-initialization process necessary for each execution of a script.
void preFinalizeForTermination(Object engineConnector)
  Performs the pre-finalization process necessary for each execution of a script.
void postFinalizeForTermination(Object engineConnector)
  Performs the post-finalization process necessary for each execution of a script.

## フィールド

Name | INTERFACE_TYPE_ID
--- | ---
Value | The type ID of this interface (value: "XNCI") 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 | getNamespaceName
--- | ---
Signature | String getNamespaceName()
Description | Gets the name of this namespace.
Parameters | None
Return | The name of this namespace.
Exception | None

Name | isMandatoryToAccessMembers
--- | ---
Signature | boolean isMandatoryToAccessMembers()
Description | Returns whether it is mandatory to specify of this namespace explicitly when accessing member functions/variables. This feature may be ignored on the script engine which does not support it.
Parameters | None
Return | Returns true if this namespace is mandatory to be specified to access members.
Exception | None

Name | getFunctions
--- | ---
Signature | ExternalFunctionConnectorInterface1[] getFunctions()
Description | Gets all functions belong to this namespace.
Parameters | None
Return | The array storing all functions belong to this namespace.
Exception | None

Name | getVariables
--- | ---
Signature | ExternalVariableConnectorInterface1[] getVariables()
Description | Gets all variables belong to this namespace.
Parameters | None
Return | The array storing all variables belong to this namespace.
Exception | None

Name | getVariables
--- | ---
Signature | ExternalStructConnectorInterface1[] getStructs()
Description | Gets all structs belong to this namespace. However, the specification of ExternalStructConnectorInterface1 (XSCI1) has not been determined yet, so as for now, the content of the XSCI1's interface file is almost empty. Hence, at least now, this method has no meanings so it always returns (should be implemented to return) an empty array. This method will be available after when XSCI1's specification is determined.
Parameters | None
Return | The array storing all structs belong to this namespace.
Exception | None

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.: preInitializeForConnection(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 XNCI1.
Parameters | None
Return | The Class representing the interface/class for communicating with the scripting engine.
Exception | None

Name | preInitializeForConnection
--- | ---
Signature | void preInitializeForConnection(Object engineConnector) throws ConnectorException
Description | Performs the pre-initialization process necessary when this plug-in is connected to the script engine. On this interface, two connection-initialization (pre- and post-) processes can be implemented. This process (pre-) will be performed before when all member variables/functions are initialized.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the initialization has failed.

Name | postInitializeForConnection
--- | ---
Signature | void postInitializeForConnection(Object engineConnector) throws ConnectorException
Description | Performs the post-initialization process necessary when this plug-in is connected to the script engine. On this interface, two connection-initialization (pre- and post-) processes can be implemented. This process (post-) will be performed after when all member variables/functions are initialized.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the initialization has failed.

Name | preFinalizeForDisconnection
--- | ---
Signature | void preFinalizeForDisconnection(Object engineConnector) throws ConnectorException
Description | Performs the pre-finalization process necessary when this plug-in is disconnected from the script engine. On this interface, two connection-finalization (pre- and post-) processes can be implemented. This process (pre-) will be performed before when all member variables/functions are finalized.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the finalization has failed.

Name | postFinalizeForDisconnection
--- | ---
Signature | void postFinalizeForDisconnection(Object engineConnector) throws ConnectorException
Description | Performs the post-finalization process necessary when this plug-in is disconnected from the script engine. On this interface, two connection-finalization (pre- and post-) processes can be implemented. This process (post-) will be performed after when all member variables/functions are finalized.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the finalization has failed.

Name | preInitializeForExecution
--- | ---
Signature | void preInitializeForExecution(Object engineConnector) throws ConnectorException
Description | Performs the pre-initialization process necessary for each execution of a script. On this interface, two execution-initialization (pre- and post-) processes can be implemented. This process (pre-) will be performed before when all member variables/functions are initialized.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the initialization has failed.

Name | postInitializeForExecution
--- | ---
Signature | void postInitializeForExecution(Object engineConnector) throws ConnectorException
Description | Performs the post-initialization process necessary for each execution of a script. On this interface, two execution-initialization (pre- and post-) processes can be implemented. This process (post-) will be performed after when all member variables/functions are initialized.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the initialization has failed.

Name | preFinalizeForTermination
--- | ---
Signature | void preFinalizeForTermination(Object engineConnector) throws ConnectorException
Description | Performs the pre-finalization process necessary for each execution of a script. On this interface, two execution-finalization (pre- and post-) processes can be implemented. This process (pre-) will be performed before when all member variables/functions are finalized.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the finalization has failed.

Name | postFinalizeForTermination
--- | ---
Signature | void postFinalizeForTermination(Object engineConnector) throws ConnectorException
Description | Performs the post-finalization process necessary for each execution of a script. On this interface, two execution-finalization (pre- and post-) processes can be implemented. This process (post-) will be performed after when all member variables/functions are finalized.
Parameters | engineConnector: The engine connector (see: getEngineConnectorClass() method).
Return | None
Exception | ConnectorException: Thrown when the finalization has failed.