PolicyConfiguration (Jakarta EE Platform API)

public interface PolicyConfiguration

このインターフェースのメソッドは、ポリシープロバイダーでポリシーステートメントを作成するためにコンテナーによって使用されます。PolicyConfiguration インターフェースを実装するオブジェクトは、対応するポリシープロバイダー内の対応するポリシーコンテキストのポリシーステートメント構成インターフェースを提供します。

ポリシーコンテキストのライフサイクルは、「オープン」、"inService"、「削除済み」の 3 つの状態によって定義されます。ポリシーコンテキストは、これら 3 つの状態のいずれかになります。

「オープン」状態のポリシーコンテキストは構成中であり、PolicyConfiguration インターフェースの任意のメソッドによって操作できます。「オープン」状態のポリシーコンテキストは、ポリシープロバイダーがアクセス決定を実行する際に使用するポリシーステートメントに Policy.refresh で同化してはなりません。ポリシーコンテキストのポリシーステートメントが関連付けられているプロバイダーによって同化されるためには、ポリシーコンテキストが "inService" 状態である必要があります。「オープン」状態のポリシーコンテキストは、コミットメソッドを呼び出すことによって "inService" 状態に移行します。

"inService" 状態のポリシーコンテキストは、関連付けられたポリシープロバイダーによってアクセス決定を実行するために使用されているポリシーステートメントに同化できます。プロバイダーは、プロバイダーのリフレッシュメソッドが呼び出されると、ポリシーステートメントを含むポリシーコンテキストを同化します。プロバイダーのリフレッシュメソッドが呼び出されると、状態が "inService" のポリシーコンテキストのみを同化する必要があります。また、各ポリシーコンテキストでサービスに投入されるポリシーステートメントは、リフレッシュの呼び出し時にコンテキストで定義されているものだけであることを確認する必要があります。"inService" 状態のポリシーコンテキストは、追加の構成には使用できず、PolicyConfigurationFactory の getPolicyConfiguration メソッドを呼び出すことによって「オープン」状態に戻すことができます。

「削除済み」状態のポリシーコンテキストは、構成に使用することも、プロバイダーに同化することもできません。状態が「削除済み」のポリシーコンテキストは、関連付けられている PolicyConfigurationFactory の getPolicyConfiguration メソッドを呼び出すことによって、後続の処理のために再利用できます。「削除済み」ポリシーコンテキストは、getPolicyConfiguration の呼び出しの結果として返されると、「オープン」状態に移行します。

次の表は、ポリシーコンテキストのライフサイクルと PolicyConfiguration インターフェースのメソッド間の対応を示しています。表の右端の 3 列は、列の先頭で識別される PolicyConfiguration 状態に対応しています。これらの列のセルの値は、対応する行の左端の列で識別されたメソッドの呼び出しの結果として生じる次の状態、または列で表される状態でメソッドの呼び出しがサポートされていないことを示します（この場合、状態は変更されません）。

PolicyConfiguration 状態テーブル
メソッド	現在の状態から次の状態へ
メソッド	削除	開く	inService
addToExcludedPolicy	サポートされていない操作	開く	サポートされていない操作
addToRole	サポートされていない操作	開く	サポートされていない操作
addToUncheckedPolicy	サポートされていない操作	開く	サポートされていない操作
コミット	サポートされていない操作	inService	inService
削除	削除	削除	削除
getContextID	削除	開く	inService
inService	削除	開く	inService
linkConfiguration	サポートされていない操作	開く	サポートされていない操作
removeExcludedPolicy	サポートされていない操作	開く	サポートされていない操作
removeRole	サポートされていない操作	開く	サポートされていない操作
removeUncheckedPolicy	サポートされていない操作	開く	サポートされていない操作

プロバイダー実装がマルチスレッド環境と互換性を持つためには、プロバイダーのリフレッシュメソッドを PolicyConfiguration インターフェースのメソッド、および PolicyConfigurationFactory の getPolicyConfiguration メソッドと inService メソッドと同期させる必要がある場合があります。

作成者:: Ron Monzillo, Gary Ellison
関連事項:: PermissionSE, PermissionCollectionSE, PolicyContextException, PolicyConfigurationFactory

メソッドのサマリー

すべてのメソッドインスタンスメソッド抽象メソッド
修飾子と型	メソッドと説明
`void`	`addToExcludedPolicy(PermissionSE permission)` この PolicyConfiguration に単一の除外されたポリシーステートメントを追加するために使用されます。
`void`	`addToExcludedPolicy(PermissionCollectionSE permissions)` この PolicyConfiguration に除外されたポリシーステートメントを追加するために使用されます。
`void`	`addToRole(StringSE roleName, PermissionSE permission)` この PolicyConfiguration の名前付きロールに単一の権限を追加するために使用されます。
`void`	`addToRole(StringSE roleName, PermissionCollectionSE permissions)` この PolicyConfiguration の名前付きロールに権限を追加するために使用されます。
`void`	`addToUncheckedPolicy(PermissionSE permission)` この PolicyConfiguration に単一の未チェックのポリシーステートメントを追加するために使用されます。
`void`	`addToUncheckedPolicy(PermissionCollectionSE permissions)` この PolicyConfiguration に未チェックのポリシーステートメントを追加するために使用されます。
`void`	`commit()` このメソッドは、インターフェースがこの PolicyConfiguration オブジェクトであるポリシーコンテキストの状態を "inService" に設定するために使用されます。
`void`	`delete()` この PolicyConfiguration からすべてのポリシーステートメントが削除され、PolicyConfiguration で delete、getContextID、inService 以外のメソッドを呼び出すと拒否され、UnsupportedOperationException がスローされるように内部状態が設定されます。
`StringSE`	`getContextID()` このメソッドは、このオブジェクトのポリシーコンテキスト識別子を返します。
`boolean`	`inService()` このメソッドは、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストが "inService" 状態にあるかどうかを判断するために使用されます。
`void`	`linkConfiguration(PolicyConfiguration link)` この構成と別の構成の間に関連を作成して、それらが同じプリンシパルからロールへのマッピングを共有するようにします。
`void`	`removeExcludedPolicy()` この PolicyConfiguration から除外されたポリシーステートメントを削除するために使用されます。
`void`	`removeRole(StringSE roleName)` この PolicyConfiguration からロールとそのすべての権限を削除するために使用されます。
`void`	`removeUncheckedPolicy()` この PolicyConfiguration から未チェックのポリシーステートメントを削除するために使用されます。

- メソッドの詳細
  - getContextID
```
StringSE getContextID()
             throws PolicyContextException
```
    このメソッドは、このオブジェクトのポリシーコンテキスト識別子を返します。
    戻り値:
    このオブジェクトのポリシーコンテキスト識別子。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    PolicyContextException - 実装が、getContextID メソッドシグネチャーによって説明されていないチェック済み例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に（構築中に）カプセル化されます。
  - addToRole
```
void addToRole(StringSE roleName,
               PermissionCollectionSE permissions)
        throws PolicyContextException
```
    この PolicyConfiguration の名前付きロールに権限を追加するために使用されます。名前付きロールが PolicyConfiguration に存在しない場合、この関数の呼び出しの結果として作成されます。
    ロールに追加されたすべての権限が「ロールにマップされた」プリンシパルに確実に付与されるようにするのは、ポリシープロバイダーのジョブです。
    パラメーター:
    roleName - 権限が追加されるロールの名前。
    permissions - ロールに追加される権限のコレクション。コレクションは、同種または異種のコレクションのいずれかです。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    UnsupportedOperationExceptionSE - このメソッドが呼び出されたときに、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストの状態が「削除済み」または "inService" である場合。
    PolicyContextException - 実装が、addToRole メソッドのシグネチャーによって説明されていないチェック済みの例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に（構築中に）カプセル化されます。
  - addToRole
```
void addToRole(StringSE roleName,
               PermissionSE permission)
        throws PolicyContextException
```
    この PolicyConfiguration の名前付きロールに単一の権限を追加するために使用されます。名前付きロールが PolicyConfiguration に存在しない場合、この関数の呼び出しの結果として作成されます。
    ロールに追加されたすべての権限が「ロールにマップされた」プリンシパルに確実に付与されるようにするのは、ポリシープロバイダーのジョブです。
    パラメーター:
    roleName - 権限が追加されるロールの名前。
    permission - ロールに追加する権限。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    UnsupportedOperationExceptionSE - このメソッドが呼び出されたときに、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストの状態が「削除済み」または "inService" である場合。
    PolicyContextException - 実装が、addToRole メソッドのシグネチャーによって説明されていないチェック済みの例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に（構築中に）カプセル化されます。
  - addToUncheckedPolicy
```
void addToUncheckedPolicy(PermissionCollectionSE permissions)
                   throws PolicyContextException
```
    この PolicyConfiguration に未チェックのポリシーステートメントを追加するために使用されます。
    パラメーター:
    permissions - チェックされていないポリシーステートメントとして追加されるアクセス許可のコレクション。コレクションは、同種または異種のコレクションのいずれかです。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    UnsupportedOperationExceptionSE - このメソッドが呼び出されたときに、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストの状態が「削除済み」または "inService" である場合。
    PolicyContextException - 実装が、addToUncheckedPolicy メソッドシグネチャーによって説明されていないチェック済み例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に（構築中に）カプセル化されます。
  - addToUncheckedPolicy
```
void addToUncheckedPolicy(PermissionSE permission)
                   throws PolicyContextException
```
    この PolicyConfiguration に単一の未チェックのポリシーステートメントを追加するために使用されます。
    パラメーター:
    permission - 未チェックのポリシーステートメントに追加する権限。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    UnsupportedOperationExceptionSE - このメソッドが呼び出されたときに、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストの状態が「削除済み」または "inService" である場合。
    PolicyContextException - 実装が、addToUncheckedPolicy メソッドシグネチャーによって説明されていないチェック済み例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に（構築中に）カプセル化されます。
  - addToExcludedPolicy
```
void addToExcludedPolicy(PermissionCollectionSE permissions)
                  throws PolicyContextException
```
    この PolicyConfiguration に除外されたポリシーステートメントを追加するために使用されます。
    パラメーター:
    permissions - 除外されたポリシーステートメントに追加されるアクセス許可のコレクション。コレクションは、同種または異種のコレクションのいずれかです。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    UnsupportedOperationExceptionSE - このメソッドが呼び出されたときに、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストの状態が「削除済み」または "inService" である場合。
    PolicyContextException - 実装が、addToExcludedPolicy メソッドシグネチャーによって説明されていないチェック済み例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に（構築中に）カプセル化されます。
  - addToExcludedPolicy
```
void addToExcludedPolicy(PermissionSE permission)
                  throws PolicyContextException
```
    この PolicyConfiguration に単一の除外されたポリシーステートメントを追加するために使用されます。
    パラメーター:
    permission - 除外されたポリシーステートメントに追加する権限。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    UnsupportedOperationExceptionSE - このメソッドが呼び出されたときに、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストの状態が「削除済み」または "inService" である場合。
    PolicyContextException - 実装が、addToExcludedPolicy メソッドシグネチャーによって説明されていないチェック済み例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に（構築中に）カプセル化されます。
  - removeRole
```
void removeRole(StringSE roleName)
         throws PolicyContextException
```
    この PolicyConfiguration からロールとそのすべての権限を削除するために使用されます。この方法は、この PolicyConfiguration と他の PolicyConfiguration との間のリンクには影響しません。
    パラメーター:
    roleName - この PolicyConfiguration から削除するロールの名前。roleName パラメーターの値が "*" であり、この PolicyConfiguration に "*" という名前のロールが存在しない場合は、この PolicyConfiguration からすべてのロールを削除する必要があります。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    UnsupportedOperationExceptionSE - このメソッドが呼び出されたときに、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストの状態が「削除済み」または "inService" である場合。
    PolicyContextException - 実装が、removeRole メソッドシグネチャーで考慮されていないチェック例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に (構築中に) カプセル化されます。
  - removeUncheckedPolicy
```
void removeUncheckedPolicy()
                    throws PolicyContextException
```
    この PolicyConfiguration から未チェックのポリシーステートメントを削除するために使用されます。この方法は、この PolicyConfiguration と他の PolicyConfiguration との間のリンクには影響しません。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    UnsupportedOperationExceptionSE - このメソッドが呼び出されたときに、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストの状態が「削除済み」または "inService" である場合。
    PolicyContextException - 実装が、removeUncheckedPolicy メソッドシグネチャーで考慮されていないチェック例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に (構築中に) カプセル化されます。
  - removeExcludedPolicy
```
void removeExcludedPolicy()
                   throws PolicyContextException
```
    この PolicyConfiguration から除外されたポリシーステートメントを削除するために使用されます。この方法は、この PolicyConfiguration と他の PolicyConfiguration との間のリンクには影響しません。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    UnsupportedOperationExceptionSE - このメソッドが呼び出されたときに、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストの状態が「削除済み」または "inService" である場合。
    PolicyContextException - 実装が、removeExcludedPolicy メソッドシグネチャーで考慮されていないチェック例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に (構築中に) カプセル化されます。
  - linkConfiguration
```
void linkConfiguration(PolicyConfiguration link)
                throws PolicyContextException
```
    この構成と別の構成の間に、同じプリンシパルからロールへのマッピングを共有するような関連を作成します。PolicyConfigurations は、アプリケーションが複数のモジュールで構成されている場合に必要となるように、共通のプリンシパルからロールへのマッピングを複数の個別に管理可能な PolicyConfigurations に適用するようにリンクされています。
    ロールを構成するポリシーステートメント、または PolicyConfiguration で除外またはチェックされていないポリシーコレクションを構成するポリシーステートメントは、別の構成にリンクされている構成の影響を受けないことに注意してください。
    この方法によって形成される関連は、対称的、推移的、べき等です。引数 PolicyConfiguration にこの PolicyConfiguration とは異なるポリシーコンテキスト識別子がない場合、関連は形成されず、以下で説明するように、例外がスローされます。
    パラメーター:
    link - この PolicyConfiguration とは異なる PolicyConfiguration への参照。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    UnsupportedOperationExceptionSE - このメソッドが呼び出されたときに、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストの状態が「削除済み」または "inService" である場合。
    IllegalArgumentExceptionSE - ポリシーコンテキストがこの PolicyConfiguration のポリシーコンテキストと同等である引数 PolicyConfiguration を指定して呼び出された場合。
    PolicyContextException - 実装が、linkConfiguration メソッドシグネチャーで考慮されていないチェック例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に (構築中に) カプセル化されます。
  - delete
```
void delete()
     throws PolicyContextException
```
    この PolicyConfiguration からすべてのポリシーステートメントが削除され、PolicyConfiguration で delete、getContextID、inService 以外のメソッドを呼び出すと拒否され、UnsupportedOperationException がスローされるように内部状態が設定されます。
    この操作は、削除された PolicyConfiguration に関連するリンクを削除する以外は、リンクされた PolicyConfigurations には影響しません。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    PolicyContextException - 実装が、delete メソッドのシグネチャーによって説明されていないチェック済みの例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に（構築中に）カプセル化されます。
  - commit
```
void commit()
     throws PolicyContextException
```
    このメソッドは、この PolicyConfiguration オブジェクトをインターフェースとするポリシーコンテキストの状態を "inService" に設定するために使用されます。状態が "inService" であるポリシーコンテキストのみが、Policy.refresh メソッドによって処理されるポリシーコンテキストに含まれます。状態が "inService" であるポリシーコンテキストは、ポリシーコンテキストのポリシーコンテキスト識別子を使用して PolicyConfiguration ファクトリの getPolicyConfiguration メソッドを呼び出すことによって、"open" 状態に戻すことができます。
    ポリシーコンテキストの状態が "inService" の場合、PolicyConfiguration オブジェクトで commit、delete、getContextID、inService 以外のメソッドを呼び出すと、UnsupportedOperationException がスローされます。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    UnsupportedOperationExceptionSE - このメソッドが呼び出されたときに、インターフェースがこの PolicyConfiguration オブジェクトであるポリシーコンテキストの状態が「削除」された場合。
    PolicyContextException - 実装が、commit メソッドのシグネチャーによって説明されていないチェック済みの例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に（構築中に）カプセル化されます。
  - inService
```
boolean inService()
           throws PolicyContextException
```
    このメソッドは、この PolicyConfiguration オブジェクトであるインターフェースを持つポリシーコンテキストが "inService" 状態にあるかどうかを判断するために使用されます。
    戻り値:
    関連付けられたポリシーコンテキストの状態が "inService" の場合は true、それ以外の場合は false。
    例外:
    SecurityExceptionSE - "setPolicy" SecurityPermission が付与されていない AccessControlContext によって呼び出された場合。
    PolicyContextException - 実装が、inService メソッドシグネチャーで考慮されていないチェック例外をスローした場合。実装クラスによってスローされた例外は、スローされた PolicyContextException に (構築中に) カプセル化されます。

インターフェース PolicyConfiguration

メソッドのサマリー

メソッドの詳細

getContextID

addToRole

addToRole

addToUncheckedPolicy

addToUncheckedPolicy

addToExcludedPolicy

addToExcludedPolicy

removeRole

removeUncheckedPolicy

removeExcludedPolicy

linkConfiguration

delete

commit

inService