VCSSL/VNANO PLUGIN INTERFACE SPECIFICATION

# Permission Authorizer Connector Interface 2 (PACI2)
Specification Document
(org.vcssl.connect.PermissionAuthorizerConnectorInterface2)

## Abstract

Permission Authorizer Connector Interface 2 (PACI2) is an interface for implementing permission-based security plug-ins.

## Status

The status of this interface is "DRAFT".

Please note that: the specification of this interface may be going to be changed continuously/largely in future.

This interface is not available yet on any scripting engine. Instead, use PACI1 at the present stage.

## 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: "PACI") referred when the plug-in will be loaded.
INTERFACE_GENERATION
  The generation of this interface (value: "2").
void setPermissionMap(Map<String, String> permissionMap, boolean setsToBase)
  Sets values of permission items, by a Map (permission map) storing names and values of permission items.
Map<String, String> getPermissionMap(boolean getsFromBase)
  Gets the Map (permission map) storing names and current values of permission items.
void requestPermission(String permissionName, Object requester, Object metaInformation)
  Receives the request of the specified permission.
void setPermissionValue(String permissionName, String value, boolean setsToBase, boolean calledByEngine)
  Sets the value of the specified permission item.
String getPermissionValue(String permissionName, boolean getFromBase, boolean calledByEngine)
  Gets the value of the specified permission item.
void storeTemporaryPermissionValues(boolean storesToBase, boolean calledByEngine)
  Stores current temporary permission settings.
void restoreTemporaryPermissionValues(boolean restoresFromBase, boolean calledByEngine, boolean calledByEngine)
  Restores current temporary permission settings.
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: "PACI") referred when the plug-in will be loaded.
Type | static final String

Name | INTERFACE_GENERATION
--- | ---
Value | The generation of this interface (value: "2").
Type | static final String

## Methods

Name | setPermissionMap
--- | ---
Signature | void setPermissionMap(Map<String, String> permissionMap, boolean setsToBase) throws ConnectorException
Description | Sets values of permission items, by a Map (permission map) storing names and values of permission items. This method will be called from script engines or applications.
Parameters | permissionMap: The Map (permission map) storing names and values of permission items. setsToBase: Specify "true" to set base permission settings, "false" to set temporary permission settings.
Return | None
Exception | ConnectorException: Thrown when invalid permission settings are detected. Also, thrown when "false" is specified to "setsToBase" but the temporary permission settings does not exist (not created yet or already disposed).

Name | getPermissionMap
--- | ---
Signature | Map<String, String> getPermissionMap(boolean getsFromBase) throws ConnectorException
Description | Gets the Map (permission map) storing names and current values of permission items. This method will be called from script engines or applications.
Parameters | getsFromBase: Specify "true" to get base permission settings, "false" to get temporary permission settings.
Return | The Map (permission map) storing names and values of permission items.
Exception | ConnectorException: Thrown when failed to get the specified permission settings. For example, thrown when "false" is specified to "setsToBase" but the temporary permission settings does not exist (not created yet or already disposed).

Name | requestPermission
--- | ---
Signature | void requestPermission(String permissionName, Object requester, Object metaInformation) throws ConnectorException
Description | Receives the request of the specified permission. If the specified permission should be allowed, this method is required to do nothing (explicitly). If the specified permission should be denied, this method throws an ConnectorException. This method will be called from other plug-ins through engine-connector interfaces.
Parameters | permissionName: The name of the requested permission item. requester: The plug-in requesting the permission. metaInformation: The information to be notified to the user (especially when the current value of the permission is set to ASK).
Return | None
Exception | ConnectorException: Thrown when the requested permission has been denied.

Name | setPermissionValue
--- | ---
Signature | void setPermissionValue(String permissionName, String value, boolean setsToBase, boolean calledByEngine) throws ConnectorException
Description | Sets the value of the specified permission item. This method will be called from script engines/applications, and may be called from other plug-ins through engine-connector interfaces. In the latter case, the permission for modifying/referencing permissions is required. However, features which enable to modify/refer permission settings from other plug-ins are unsupported yet by engine-connector interfaces (e.g.: ECI1). Furthermore, it is unckear whether it will be supported in future. This method is a kind of "mockup" of the above feature, at the present stage.
Parameters | permissionName: The name of the permission item to be set its value. value: The value to be set. setsToBase: Specify true to set the value of base permission settings, or false to set the value of temporary permission settings. calledByEngine: Specify "true" when calling this method by the scripting engine.
Return | None
Exception | ConnectorException: Thrown when the requested action has been denied, or unsupported, especially when "false" is specified to "calledByEngine". Also, thrown when "false" is specified to "setsToBase" but the temporary permission settings does not exist (not created yet or already disposed).

Name | getPermissionValue
--- | ---
Signature | String getPermissionValue(String permissionName, boolean getFromBase, boolean calledByEngine) throws ConnectorException
Description | Gets the value of the specified permission item. This method will be called from script engines/applications, and may be called from other plug-ins through engine-connector interfaces. In the latter case, the permission for modifying/referencing permissions is required. However, features which enable to modify/refer permission settings from other plug-ins are unsupported yet by engine-connector interfaces (e.g.: ECI1). Furthermore, it is unckear whether it will be supported in future. This method is a kind of "mockup" of the above feature, at the present stage.
Parameters | permissionName: The name of the permission item to be gotten its value. getFromBase: Specify true to get the value of base permission settings, or false to get the value of temporary permission settings. calledByEngine: Specify true when calling this method by the scripting engine.
Return | he value of the specified permission item.
Exception | Thrown when the requested action has been denied, or unsupported, especially when "false" is specified to "calledByEngine". Also, thrown when "false" is specified to "getFromBase" but the temporary permission settings does not exist (not created yet or already disposed).

Name | storeTemporaryPermissionValues
--- | ---
Signature | void storeTemporaryPermissionValues(boolean storesToBase, boolean calledByEngine) throws ConnectorException
Description | Stores current temporary permission settings. Stores current temporary permission settings for restoring it later by restoreTemporaryPermissionValues(boolean restoresFromBase, boolean calledByEngine) method, or overwriting permanent permission settings. This method will be called from script engines/applications, and may be called from other plug-ins through engine-connector interfaces. In the latter case, the permission for modifying/referencing permissions is required. However, features which enable to modify/refer permission settings from other plug-ins are unsupported yet by engine-connector interfaces (e.g.: ECI1). Furthermore, it is unckear whether it will be supported in future. This method is a kind of "mockup" of the above feature, at the present stage.
Parameters | storesToBase: Specify true to store by overwriting base permission settings, or false to store temporary for recovering later by restoreTemporaryPermissionValues(boolean restoresFromBase) method. calledByEngine: Specify true when calling this method by the scripting engine.
Return | None
Exception | Thrown when the requested action has been denied, or unsupported, especially when "false" is specified to "calledByEngine". Also, thrown when "false" is specified to "getFromBase" but the temporary permission settings does not exist (not created yet or already disposed).

Name | restoreTemporaryPermissionValues
--- | ---
Signature | void restoreTemporaryPermissionValues(boolean restoresFromBase, boolean calledByEngine, boolean calledByEngine) throws ConnectorException
Description | Restores current temporary permission settings. This method will be called from script engines/applications, and may be called from other plug-ins through engine-connector interfaces. In the latter case, the permission for modifying/referencing permissions is required (but unsupported yet). However, features which enable to modify/refer permission settings from other plug-ins are unsupported yet by engine-connector interfaces (e.g.: ECI1). Furthermore, it is unckear whether it will be supported in future. This method is a kind of "mockup" of the above feature, at the present stage.
Parameters | restoresFromBase: Specify true to restore by copying values from base permission settings, or false to restore by loading settings stored temporary by restoreTemporaryPermissionValues(boolean restoresFromBase) method. calledByEngine: Specify true when calling this method by the scripting engine.
Return | None
Exception | Thrown when the requested action has been denied, or unsupported, especially when "false" is specified to "calledByEngine". Also, thrown when "false" is specified to "getFromBase" but the temporary permission settings does not exist (not created yet or already disposed).

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 PACI1.
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.