|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface PolicyConfiguration
The methods of this interface are used by containers to create policy statements in a Policy provider. An object that implements the PolicyConfiguration interface provides the policy statement configuration interface for a corresponding policy context within the corresponding Policy provider.
The life cycle of a policy context is defined by three states; "open", "inService", and "deleted". A policy context is in one of these three states.
A policy context in the "open" state is in the process of being
configured, and may be operated on by any of the methods of the
PolicyConfiguration interface. A policy context in the "open" state
must not be assimilated at Policy.refresh
into the policy
statements used by the Policy provider in performing its access decisions.
In order for the policy statements of a policy context to be assimilated
by the associated provider, the policy context must be in the
"inService" state. A policy context in the "open" state is transitioned to
the "inService" state by calling the commit method.
A policy context in the "inService" state is available for assimilation into the policy statements being used to perform access decisions by the associated Policy provider. Providers assimilate policy contexts containing policy statements when the refresh method of the provider is called. When a provider's refresh method is called, it must assimilate only those policy contexts whose state is "inService" and it must ensure that the policy statements put into service for each policy context are only those defined in the context at the time of the call to refresh. A policy context in the "inService" state is not available for additional configuration and may be returned to the "open" state by calling the getPolicyConfiguration method of the PolicyConfigurationFactory.
A policy context in the "deleted" state is neither available for configuration, nor is it available for assimilation into the Provider. A policy context whose state is "deleted" may be reclaimed for subsequent processing by calling the getPolicyConfiguration method of the associated PolicyConfigurationFactory. A "deleted" policy context is transitioned to the "open" state when it it returned as a result of a call to getPolicyConfiguration.
The following table captures the correspondence between the policy context
life cycle and the methods of the PolicyConfiguration interface.
The rightmost 3 columns of the table correspond to the
PolicyConfiguration state identified at the head of the column.
The values in the cells of these columns indicate
the next state resulting from a call to the method
identifed in the leftmost column of the corresponding row, or that
calling the method is unsupported in the state
represented by the column (in which case the state will remain unchanged).
Method | Current State to Next State | ||
---|---|---|---|
deleted | open | inService | |
addToExcludedPolicy | Unsupported Operation | open | Unsupported Operation |
addToRole | Unsupported Operation | open | Unsupported Operation |
addToUncheckedPolicy | Unsupported Operation | open | Unsupported Operation |
commit | Unsupported Operation | inService | inService |
delete | deleted | deleted | deleted |
getContextID | deleted | open | inService |
inService | deleted | open | inService |
linkConfiguration | Unsupported Operation | open | Unsupported Operation |
removeExcludedPolicy | Unsupported Operation | open | Unsupported Operation |
removeRole | Unsupported Operation | open | Unsupported Operation |
removeUncheckedPolicy | Unsupported Operation | open | Unsupported Operation |
For a provider implementation to be compatible with multi-threaded environments, it may be necessary to synchronize the refresh method of the provider with the methods of its PolicyConfiguration interface and with the getPolicyConfiguration and inService methods of its PolicyConfigurationFactory.
Permission
,
PermissionCollection
,
PolicyContextException
,
PolicyConfigurationFactory
Method Summary | |
---|---|
void |
addToExcludedPolicy(java.security.Permission permission)
Used to add a single excluded policy statement to this PolicyConfiguration. |
void |
addToExcludedPolicy(java.security.PermissionCollection permissions)
Used to add excluded policy statements to this PolicyConfiguration. |
void |
addToRole(java.lang.String roleName,
java.security.Permission permission)
Used to add a single permission to a named role in this PolicyConfiguration. |
void |
addToRole(java.lang.String roleName,
java.security.PermissionCollection permissions)
Used to add permissions to a named role in this PolicyConfiguration. |
void |
addToUncheckedPolicy(java.security.Permission permission)
Used to add a single unchecked policy statement to this PolicyConfiguration. |
void |
addToUncheckedPolicy(java.security.PermissionCollection permissions)
Used to add unchecked policy statements to this PolicyConfiguration. |
void |
commit()
This method is used to set to "inService" the state of the policy context whose interface is this PolicyConfiguration Object. |
void |
delete()
Causes all policy statements to be deleted from this PolicyConfiguration and sets its internal state such that calling any method, other than delete, getContextID, or inService on the PolicyConfiguration will be rejected and cause an UnsupportedOperationException to be thrown. |
java.lang.String |
getContextID()
This method returns this object's policy context identifier. |
boolean |
inService()
This method is used to determine if the policy context whose interface is this PolicyConfiguration Object is in the "inService" state. |
void |
linkConfiguration(PolicyConfiguration link)
Creates a relationship between this configuration and another such that they share the same principal-to-role mappings. |
void |
removeExcludedPolicy()
Used to remove any excluded policy statements from this PolicyConfiguration. |
void |
removeRole(java.lang.String roleName)
Used to remove a role and all its permissions from this PolicyConfiguration. |
void |
removeUncheckedPolicy()
Used to remove any unchecked policy statements from this PolicyConfiguration. |
Method Detail |
---|
java.lang.String getContextID() throws PolicyContextException
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the getContextID method signature. The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void addToRole(java.lang.String roleName, java.security.PermissionCollection permissions) throws PolicyContextException
It is the job of the Policy provider to ensure that all the permissions added to a role are granted to principals "mapped to the role".
roleName
- the name of the Role to which the permissions are
to be added.
permissions
- the collection of permissions to be added
to the role. The collection may be either a homogenous or
heterogenous collection.
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
java.lang.UnsupportedOperationException
- if the state of the policy context whose interface is this
PolicyConfiguration Object is "deleted" or "inService" when this
method is called.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the addToRole method signature. The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void addToRole(java.lang.String roleName, java.security.Permission permission) throws PolicyContextException
It is the job of the Policy provider to ensure that all the permissions added to a role are granted to principals "mapped to the role".
roleName
- the name of the Role to which the permission is
to be added.
permission
- the permission to be added
to the role.
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
java.lang.UnsupportedOperationException
- if the state of the policy context whose interface is this
PolicyConfiguration Object is "deleted" or "inService" when this
method is called.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the addToRole method signature. The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void addToUncheckedPolicy(java.security.PermissionCollection permissions) throws PolicyContextException
permissions
- the collection of permissions to be added
as unchecked policy statements. The collection may be either
a homogenous or heterogenous collection.
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
java.lang.UnsupportedOperationException
- if the state of the policy context whose interface is this
PolicyConfiguration Object is "deleted" or "inService" when this
method is called.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the addToUncheckedPolicy method signature.
The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void addToUncheckedPolicy(java.security.Permission permission) throws PolicyContextException
permission
- the permission to be added
to the unchecked policy statements.
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
java.lang.UnsupportedOperationException
- if the state of the policy context whose interface is this
PolicyConfiguration Object is "deleted" or "inService" when this
method is called.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the addToUncheckedPolicy method signature.
The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void addToExcludedPolicy(java.security.PermissionCollection permissions) throws PolicyContextException
permissions
- the collection of permissions to be added
to the excluded policy statements. The collection may be either
a homogenous or heterogenous collection.
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
java.lang.UnsupportedOperationException
- if the state of the policy context whose interface is this
PolicyConfiguration Object is "deleted" or "inService" when this
method is called.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the addToExcludedPolicy method signature.
The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void addToExcludedPolicy(java.security.Permission permission) throws PolicyContextException
permission
- the permission to be added
to the excluded policy statements.
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
java.lang.UnsupportedOperationException
- if the state of the policy context whose interface is this
PolicyConfiguration Object is "deleted" or "inService" when this
method is called.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the addToExcludedPolicy method signature.
The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void removeRole(java.lang.String roleName) throws PolicyContextException
roleName
- the name of the role to remove from this
PolicyConfiguration. If the value of the roleName parameter is "*"
and no role with name "*" exists in this PolicyConfiguration,
then all roles must be removed from this PolicyConfiguration.
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
java.lang.UnsupportedOperationException
- if the state of the policy context whose interface is this
PolicyConfiguration Object is "deleted" or "inService" when this
method is called.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the removeRole method signature. The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void removeUncheckedPolicy() throws PolicyContextException
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
java.lang.UnsupportedOperationException
- if the state of the policy context whose interface is this
PolicyConfiguration Object is "deleted" or "inService" when this
method is called.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the removeUncheckedPolicy method signature.
The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void removeExcludedPolicy() throws PolicyContextException
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
java.lang.UnsupportedOperationException
- if the state of the policy context whose interface is this
PolicyConfiguration Object is "deleted" or "inService" when this
method is called.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the removeExcludedPolicy method signature.
The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void linkConfiguration(PolicyConfiguration link) throws PolicyContextException
Note that the policy statements which comprise a role, or comprise the excluded or unchecked policy collections in a PolicyConfiguration are unaffected by the configuration being linked to another.
link
- a reference to a different PolicyConfiguration than this
PolicyConfiguration.
The relationship formed by this method is symetric, transitive and idempotent. If the argument PolicyConfiguration does not have a different Policy context identifier than this PolicyConfiguration no relationship is formed, and an exception, as described below, is thrown.
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
java.lang.UnsupportedOperationException
- if the state of the policy context whose interface is this
PolicyConfiguration Object is "deleted" or "inService" when this
method is called.
java.lang.IllegalArgumentException
- if called with an argument PolicyConfiguration whose Policy context
is equivalent to that of this PolicyConfiguration.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the linkConfiguration method signature. The exception
thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void delete() throws PolicyContextException
This operation has no affect on any linked PolicyConfigurations other than removing any links involving the deleted PolicyConfiguration.
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the delete method signature. The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.void commit() throws PolicyContextException
When the state of a policy context is "inService", calling any method other than commit, delete, getContextID, or inService on its PolicyConfiguration Object will cause an UnsupportedOperationException to be thrown.
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
java.lang.UnsupportedOperationException
- if the state of the policy context whose interface is this
PolicyConfiguration Object is "deleted" when this
method is called.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the commit method signature. The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.boolean inService() throws PolicyContextException
java.lang.SecurityException
- if called by an AccessControlContext that has not been
granted the "setPolicy" SecurityPermission.
PolicyContextException
- if the implementation throws a checked exception that has not been
accounted for by the inService method signature. The exception thrown
by the implementation class will be encapsulated (during construction)
in the thrown PolicyContextException.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright © 2009, 2010, Oracle Corporation and/or its affiliates. All Rights Reserved. Use is subject to license terms.
Generated on 4-June-2010 04:34