VCSSL/Vnano プラグイン インターフェース 仕様書

# Permission Authorizer Connector Interface 1 (PACI1)
インターフェース仕様書
(org.vcssl.connect.PermissionAuthorizerConnectorInterface1)

## 概要

Permission Authorizer Connector Interface 1 (PACI1) は、 パーミッションベースのセキュリティプラグインを実装するためのインターフェースの一つです。

PACI1 形式のプラグインは、スクリプトエンジンを介して、他のプラグインからのパーミッション要求を受け取り、 それを許可/拒否するかを（必要に応じてユーザーに尋ねた上で）決定します。

どういった形のUIが上記の決定処理に適しているかは、アプリケーション側のUIや用途などにかなり依存します。 そのため、アプリケーション側で上記の決定処理のUIをデザインし、このインターフェースを実装する事で、 それをスクリプトエンジンに接続して使用する事ができます。

なお、PACI 1 では、下記のような 2 種類のパーミッション設定の存在を想定しています:

基礎パーミッション設定 (Base permission settings)：
  アプリケーションやスクリプトエンジンに明示的に設定され、 各スクリプトの実行開始時に自動適用されるパーミッション設定です。
一時パーミッション設定 (Temporary permission settings)：
  各スクリプトの実行中のみ持続し、ユーザーの許可操作などによって変化し得る、一時的なパーミッション設定です。

スクリプトが実行される際には、まず基礎パーミッション設定の内容が一時パーミッション設定にコピーされ、 その後は一時パーミッション設定を参照しながら（必要に応じて設定が変化しながら）スクリプトが実行されます。 次のスクリプトが実行される際には、一時パーミッション設定は再度、基礎パーミッション設定の内容でリセットされます。

一時パーミッション設定が存在する理由は、同じ許可要求をユーザーに何度も求める事を避けるためです。 例えば、ファイル書き込みの基礎パーミッション設定が ASK に設定されていた場合、 仮にそれだけを参照して判断すると、ファイルに一行書き込むごとに、毎回ユーザーに許可を求める事になります（例えば100行のファイルなら100回）。 それはユーザーにとって非常に面倒なため、恐らく「このスクリプトの終了まで、同種のパーミッションを常に許可する」といった操作のサポートが必要になります。 そして、そのような操作は、一時パーミッション設定の内容をスクリプト実行中に書き換える事で実現できます。

## ステータス

このインターフェースの現在のステータスは "FINALIZED"（確定済み）です。

このインターフェースの仕様は、2022年9月30日時点で最終確定しました。今後は原則として、ドキュメントやコメント類以外の変更は加えられません。

現在は Vnano のスクリプトエンジンでサポートされ、同エンジンを搭載したアプリケーションのプラグイン開発において利用できます。

## ライセンス

このインターフェースは、実質的な著作権フリー/パブリックドメインである CC0 に基づいて公開されています。

## フィールド/メソッド等の一覧

INTERFACE_TYPE_ID
  プラグインのロード時に参照される、このインターフェースの形式ID（値: "PACI"）です。
INTERFACE_GENERATION
  このインターフェースの世代名です（値: "1"）。
void setPermissionMap(Map<String, String> permissionMap, boolean setsToBase)
  パーミッション項目の名前と値を格納するマップ（パーミッションマップ）によって、各パーミッションの値を設定します。
Map<String, String> getPermissionMap(boolean getsFromBase)
  パーミッション項目の名前と現在の値を格納するマップ（パーミッションマップ）を返します。
void requestPermission(String permissionName, Object requester, Object metaInformation)
  指定されたパーミッションの要求を受け付けます。
Class<?> getEngineConnectorClass()
  スクリプトエンジンと情報をやり取りする際に使用するオブジェクトである「エンジンコネクタ」の、インターフェースまたはクラスを返します。
void initializeForConnection(Object engineConnector)
  このプラグインが、スクリプトエンジンに接続される際に必要となる初期化処理を実行します。
void finalizeForDisconnection(Object engineConnector)
  このプラグインが、スクリプトエンジンから接続解除される際に必要となる終了時処理を実行します。
void initializeForExecution(Object engineConnector)
  スクリプトの実行毎に必要な初期化処理を実行します。
void finalizeForTermination(Object engineConnector)
  スクリプトの実行毎に必要な終了時処理を実行します。

## フィールド

名前 | INTERFACE_TYPE_ID
--- | ---
値の意味 | プラグインのロード時に参照される、このインターフェースの形式ID（値: "PACI"）です。
データ型 | static final String

名前 | INTERFACE_GENERATION
--- | ---
値の意味 | このインターフェースの世代名です（値: "1"）。
データ型 | static final String

## メソッド

名前 | setPermissionMap
--- | ---
宣言形式 | void setPermissionMap(Map<String, String> permissionMap, boolean setsToBase) throws ConnectorException
機能 | パーミッション項目の名前と値を格納するマップ（パーミッションマップ）によって、各パーミッションの値を設定します。 このメソッドは、スクリプトエンジンやアプリケーションから呼び出されます。
引数 | permissionMap: パーミッション項目の名前と値を格納するマップ（パーミッションマップ） setsToBase: 基礎パーミッションとして設定する場合は true、一時パーミッションとして設定する場合は false を指定します
戻り値 | なし
例外 | ConnectorException: 無効なパーミッション設定が検出された際にスローされます。 また、一時パーミッションが存在しないタイミングで、一時パーミッションに対する設定が行われた際にもスローされます。

名前 | getPermissionMap
--- | ---
宣言形式 | Map<String, String> getPermissionMap(boolean getsFromBase) throws ConnectorException
機能 | パーミッション項目の名前と現在の値を格納するマップ（パーミッションマップ）を返します。 このメソッドは、スクリプトエンジンやアプリケーションから呼び出されます。
引数 | getsFromBase: 基礎パーミッションを取得する場合は true、一時パーミッションを取得する場合は false を指定します。
戻り値 | パーミッション項目の名前と値を格納するマップ（パーミッションマップ）
例外 | ConnectorException: 指定したパーミッション設定の取得に失敗した場合された際にスローされます。 例えば、一時パーミッションが存在しないタイミングで、一時パーミッションの取得が要求された際にスローされます。

名前 | requestPermission
--- | ---
宣言形式 | void requestPermission(String permissionName, Object requester, Object metaInformation) throws ConnectorException
機能 | 指定されたパーミッションの要求を受け付けます。 指定されたパーミッションが許可されるべき場合には、このメソッドは（対外的には）何もする必要はありません。 指定されたパーミッションが拒否されるべき場合には、このメソッドは ConnectorException 例外を発生させます。 このメソッドは, エンジンコネクターインターフェースを介して、他のプラグインから呼び出されます。
引数 | permissionName: 要求されているパーミッション項目の名称。 requester: パーミッションを要求しているプラグイン。 metaInformation: 必要に応じてユーザーに通知されるメタ情報 （特に、パーミッション値が ASK に設定されている際などに表示されます）。
戻り値 | なし
例外 | ConnectorException: 要求したパーミッションが拒否された場合にスローされます。

名前 | getEngineConnectorClass
--- | ---
宣言形式 | Class<?> getEngineConnectorClass()
機能 | スクリプトエンジンと情報をやり取りする際に使用するオブジェクトである「エンジンコネクタ」の、 インターフェースまたはクラスを返します。 このメソッドで戻り値として指定したインターフェースまたはクラスの実装インスタンスが、 initializeForConnection(Object engineConnector) メソッド等の初期化/終了時メソッド群の、引数 engineConnector に渡されます。 利用可能なエンジンコネクタの形式は、スクリプトエンジンの実装に依存しますが、 少なくとも ECI1 は利用可能である事が、 PACI1の仕様上保証されています。
引数 | なし
戻り値 | 使用したいエンジンコネクタのインターフェースまたはクラス。
例外 | なし

名前 | initializeForConnection
--- | ---
宣言形式 | void initializeForConnection(Object engineConnector) throws ConnectorException
機能 | このプラグインが、スクリプトエンジンに接続される際に必要となる初期化処理を実行します。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 初期化処理に失敗した場合にスローされます。

名前 | finalizeForDisconnection
--- | ---
宣言形式 | void finalizeForDisconnection(Object engineConnector) throws ConnectorException
機能 | このプラグインが、スクリプトエンジンから接続解除される際に必要となる終了時処理を実行します。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 終了時処理に失敗した場合にスローされます。

名前 | initializeForExecution
--- | ---
宣言形式 | void initializeForExecution(Object engineConnector) throws ConnectorException
機能 | スクリプトの実行毎に必要な初期化処理を実行します。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 初期化処理に失敗した場合にスローされます。

名前 | finalizeForTermination
--- | ---
宣言形式 | void finalizeForTermination(Object engineConnector) throws ConnectorException
機能 | スクリプトの実行毎に必要な終了時処理を実行します。
引数 | engineConnector: エンジンコネクタ （getEngineConnectorClass() メソッド参照）
戻り値 | なし
例外 | ConnectorException: 終了時処理に失敗した場合にスローされます。