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

# Permission Authorizer Connector Interface 2 (PACI2)
インターフェース仕様書
(org.vcssl.connect.PermissionAuthorizerConnectorInterface2)

## 概要

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

## ステータス

このインターフェースの現在のステータスは "DRAFT"（草案）です。

このインターフェースの仕様は、まだ大幅かつ継続的な変更が加えられる可能性が高く、その点に常に留意が必要な段階です。

このインターフェースを現在利用可能なスクリプトエンジンは、まだ存在しません。現時点では、代わりに PACI1 を使用してください。

## ライセンス

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

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

INTERFACE_TYPE_ID
  プラグインのロード時に参照される、このインターフェースの形式ID（値: "PACI"）です。
INTERFACE_GENERATION
  このインターフェースの世代名です（値: "2"）。
void setPermissionMap(Map<String, String> permissionMap, boolean setsToBase)
  パーミッション項目の名前と値を格納するマップ（パーミッションマップ）によって、各パーミッションの値を設定します。
Map<String, String> getPermissionMap(boolean getsFromBase)
  パーミッション項目の名前と現在の値を格納するマップ（パーミッションマップ）を返します。
void requestPermission(String permissionName, Object requester, Object metaInformation)
  指定されたパーミッションの要求を受け付けます。
void setPermissionValue(String permissionName, String value, boolean setsToBase, boolean calledByEngine)
  指定されたパーミッション項目の値を設定します。
String getPermissionValue(String permissionName, boolean getFromBase, boolean calledByEngine)
  指定されたパーミッション項目の値を取得します。
void storeTemporaryPermissionValues(boolean storesToBase, boolean calledByEngine)
  現在の一時的なパーミッション状態を保存します。
void restoreTemporaryPermissionValues(boolean restoresFromBase, boolean calledByEngine, boolean calledByEngine)
  現在の一時的なパーミッション状態を復元します。
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: 要求したパーミッションが拒否された場合にスローされます。

名前 | setPermissionValue
--- | ---
宣言形式 | void setPermissionValue(String permissionName, String value, boolean setsToBase, boolean calledByEngine) throws ConnectorException
機能 | 指定されたパーミッション項目の値を設定します。 このメソッドは、スクリプトエンジン/アプリケーション側から呼ばれる場合と、 エンジンコネクターインターフェースを介して他のプラグインから呼ばれる場合があります。 後者の場合には、パーミッション編集/参照に対するパーミッションが必要です。 ただし、プラグインから明示的にパーミッションを編集/参照する操作は、将来的なサポートの可能性が検討されているのみであり、最終的にサポートされるかどうかも含めて、現状では不透明です。 そのため、EngineConnectorInterface1 にも該当機能は存在しません。従って、当面の間は、calledByEngine に false を指定した呼び出しが行われる事はありません。
引数 | permissionName: 値を設定するパーミッション項目の名称。 value: 設定する値。 setsToBase: 基礎パーミッションの値を設定する場合は true、一時パーミッションの値を設定する場合は false を指定します。 calledByEngine: スクリプトエンジン/アプリケーション側からの操作の場合は true、それ以外（プラグイン等）からの操作の場合は false を指定します。
戻り値 | なし
例外 | ConnectorException: 特に calledByEngine を false に指定した呼び出しにおいて、要求した操作が拒否された場合や、未サポートの場合にスローされます。 また、一時パーミッションが存在しないタイミングで、一時パーミッションに対する設定が行われた際にもスローされます。

名前 | getPermissionValue
--- | ---
宣言形式 | String getPermissionValue(String permissionName, boolean getFromBase, boolean calledByEngine) throws ConnectorException
機能 | 指定されたパーミッション項目の値を取得します。 このメソッドは, スクリプトエンジン/アプリケーション側から呼ばれる場合と、 エンジンコネクターインターフェースを介して他のプラグインから呼ばれる場合があります。 後者の場合には、パーミッション編集/参照に対するパーミッションが必要です。 ただし、プラグインから明示的にパーミッションを編集/参照する操作は、将来的なサポートの可能性が検討されているのみであり、最終的にサポートされるかどうかも含めて、現状では不透明です。 そのため、EngineConnectorInterface1 にも該当機能は存在しません。従って、当面の間は、calledByEngine に false を指定した呼び出しが行われる事はありません。
引数 | permissionName: 値を取得するパーミッション項目の名称。 getFromBase: 基礎パーミッションの値を取得する場合は true、一時パーミッションの値を取得する場合は false を指定します。 calledByEngine: スクリプトエンジン/アプリケーション側からの操作の場合は true、それ以外（プラグイン等）からの操作の場合は false を指定します。
戻り値 | 指定されたパーミッション項目の値
例外 | ConnectorException: 特に calledByEngine を false に指定した呼び出しにおいて、要求した操作が拒否された場合や、未サポートの場合にスローされます。 また、一時パーミッションが存在しないタイミングで、一時パーミッションに対する設定が行われた際にもスローされます。

名前 | storeTemporaryPermissionValues
--- | ---
宣言形式 | void storeTemporaryPermissionValues(boolean storesToBase, boolean calledByEngine) throws ConnectorException
機能 | 現在の一時的なパーミッション状態を保存します。 現在の一時的なパーミッション状態を保存します。 後で restoreTemporaryPermissionValues(boolean restoresFromBase, boolean calledByEngine) メソッドによって復元可能な形に、またはパーマネント設定値を上書きする事で保存します このメソッドは、スクリプトエンジン/アプリケーション側から呼ばれる場合と、 エンジンコネクターインターフェースを介して他のプラグインから呼ばれる場合があります。 後者の場合には、パーミッション編集/参照に対するパーミッションが必要です。 ただし、プラグインから明示的にパーミッションを編集/参照する操作は、将来的なサポートの可能性が検討されているのみであり、最終的にサポートされるかどうかも含めて、現状では不透明です。 そのため、EngineConnectorInterface1 にも該当機能は存在しません。従って、当面の間は、calledByEngine に false を指定した呼び出しが行われる事はありません。
引数 | storesToBase: 基礎パーミッション設定を上書きする形で保存する場合は true を指定します。 後で restoreTemporaryPermissionValues(boolean restoresFromBase) メソッドで復元するために一時保存する場合は false を指定します。 calledByEngine: スクリプトエンジン/アプリケーション側からの操作の場合は true、それ以外（プラグイン等）からの操作の場合は false を指定します。
戻り値 | なし
例外 | ConnectorException: 特に calledByEngine を false に指定した呼び出しにおいて、要求した操作が拒否された場合や、未サポートの場合にスローされます。 また、一時パーミッションが存在しないタイミングで呼び出された際にもスローされます。

名前 | restoreTemporaryPermissionValues
--- | ---
宣言形式 | void restoreTemporaryPermissionValues(boolean restoresFromBase, boolean calledByEngine, boolean calledByEngine) throws ConnectorException
機能 | 現在の一時的なパーミッション状態を復元します。 現在の一時的なパーミッション状態を保存します。 後で restoreTemporaryPermissionValues(boolean restoresFromBase) メソッドによって復元可能な形に、またはパーマネント設定値を上書きする事で保存します このメソッドは、スクリプトエンジン/アプリケーション側から呼ばれる場合と、 エンジンコネクターインターフェースを介して他のプラグインから呼ばれる場合があります。 後者の場合には、パーミッション編集/参照に対するパーミッションが必要です。 ただし、プラグインから明示的にパーミッションを編集/参照する操作は、将来的なサポートの可能性が検討されているのみであり、最終的にサポートされるかどうかも含めて、現状では不透明です。 そのため、EngineConnectorInterface1 にも該当機能は存在しません。従って、当面の間は、calledByEngine に false を指定した呼び出しが行われる事はありません。
引数 | restoresFromBase: 基礎パーミッション設定の値を読み込んで復元する場合は true を指定します。 事前に storeTemporaryPermissionValues(boolean storesToBase) メソッドで一時保存された設定から復元する場合は false を指定します。 calledByEngine: スクリプトエンジン/アプリケーション側からの操作の場合は true、それ以外（プラグイン等）からの操作の場合は false を指定します。
戻り値 | なし
例外 | ConnectorException: 特に calledByEngine を false に指定した呼び出しにおいて、要求した操作が拒否された場合や、未サポートの場合にスローされます。 また、一時パーミッションが存在しないタイミングで呼び出された際にもスローされます。

名前 | 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: 終了時処理に失敗した場合にスローされます。