Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.security.jacc
Interface PolicyConfiguration

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

PolicyConfiguration State Table
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.

Version:
  $Revision: 1.1 $
Author:
  Scott.Stark@jboss.org, Ron Monzillo, Gary Ellison (javadoc)
See Also:
  `http://java.sun.com/j2ee/1.4/docs/api/`

Method Summary
`void` | `addToExcludedPolicy(Permission permission)` Adds a single excluded permission to the PolicyConfiguration.
`void` | `addToExcludedPolicy(PermissionCollection permissions)` Adds a collection of excluded permissions to the PolicyConfiguration
`void` | `addToRole(String roleName, Permission permission)` Add a single permission to a named role in the PolicyConfiguration.
`void` | `addToRole(String roleName, PermissionCollection permissions)` Add permissions to a named role in the PolicyConfiguration.
`void` | `addToUncheckedPolicy(Permission permission)` Add a single unchecked permission to the PolicyConfiguration.
`void` | `addToUncheckedPolicy(PermissionCollection permissions)` Add unchecked permissions to the 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.
`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(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

### addToExcludedPolicy

    public void addToExcludedPolicy(Permission permission)
                             throws PolicyContextException

  Adds a single excluded permission to the PolicyConfiguration.

  Parameters:
    `permission` -
  Throws:
    `PolicyContextException`

### addToExcludedPolicy

    public void addToExcludedPolicy(PermissionCollection permissions)
                             throws PolicyContextException

  Adds a collection of excluded permissions to the PolicyConfiguration

  Parameters:
    `permissions` -
  Throws:
    `PolicyContextException`

### addToRole

    public void addToRole(String roleName,
                          Permission permission)
                   throws PolicyContextException

  Add a single permission to a named role in the PolicyConfiguration. If the named Role does not exist in the PolicyConfiguration, it is created as a result of the call to this function.

  Parameters:
    `roleName` -
    `permission` -
  Throws:
    `PolicyContextException`

### addToRole

    public void addToRole(String roleName,
                          PermissionCollection permissions)
                   throws PolicyContextException

  Add permissions to a named role in the PolicyConfiguration. If the named Role does not exist in the PolicyConfiguration, it is created as a result of the call to this function.

  Parameters:
    `roleName` -
    `permissions` -
  Throws:
    `PolicyContextException`

### addToUncheckedPolicy

    public void addToUncheckedPolicy(Permission permission)
                              throws PolicyContextException

  Add a single unchecked permission to the PolicyConfiguration.

  Parameters:
    `permission` -
  Throws:
    `PolicyContextException`

### addToUncheckedPolicy

    public void addToUncheckedPolicy(PermissionCollection permissions)
                              throws PolicyContextException

  Add unchecked permissions to the PolicyConfiguration.

  Parameters:
    `permissions` -
  Throws:
    `PolicyContextException`

### commit

    public void commit()
                throws PolicyContextException

  This method is used to set to "inService" the state of the policy context whose interface is this PolicyConfiguration Object. Only those policy contexts whose state is "inService" will be included in the policy contexts processed by the Policy.refresh method. A policy context whose state is "inService" may be returned to the "open" state by calling the getPolicyConfiguration method of the PolicyConfiguration factory with the policy context identifier of the policy context. 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.

  Throws:
    `SecurityException` - - when the caller does not have a SecurityPermission("setPolicy") permission.
    `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.

### delete

    public void delete()
                throws PolicyContextException

  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. This operation has no affect on any linked PolicyConfigurations other than removing any links involving the deleted PolicyConfiguration.

  Throws:
    `SecurityException` - - when the caller does not have a SecurityPermission("setPolicy") permission.
    `PolicyContextException`

### getContextID

    public String getContextID()
                        throws PolicyContextException

  This method returns this object's policy context identifier.

  Returns:
    this object's policy context identifier.
  Throws:
    `SecurityException` - - when the caller does not have a SecurityPermission("setPolicy") permission.
    `PolicyContextException`

### inService

    public boolean inService()
                      throws PolicyContextException

  This method is used to determine if the policy context whose interface is this PolicyConfiguration Object is in the "inService" state.

  Returns:
    true if the state of the associated policy context is "inService", false otherwise.
  Throws:
    `PolicyContextException`

### linkConfiguration

    public void linkConfiguration(PolicyConfiguration link)
                           throws PolicyContextException

  Creates a relationship between this configuration and another such that they share the same principal-to-role mappings. PolicyConfigurations are linked to apply a common principal-to-role mapping to multiple seperately manageable PolicyConfigurations, as is required when an application is composed of multiple modules.

  Parameters:
    `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 IllegalArgumentException is thrown.
  Throws:
    `SecurityException` - - when the caller does not have a SecurityPermission("setPolicy") permission.
    `IllegalArgumentException` - - if called with an argument PolicyConfiguration whose Policy context is equivalent to that of this PolicyConfiguration.
    `PolicyContextException`

### removeExcludedPolicy

    public void removeExcludedPolicy()
                              throws PolicyContextException

  Used to remove any excluded policy statements from this PolicyConfiguration

  Throws:
    `SecurityException` - - when the caller does not have a SecurityPermission("setPolicy") permission.
    `UnsupportedOperationException` - - if the state of the policy context whose interface is this PolicyConfiguration Object is "deleted" or "inService" when this method is called.
    `PolicyContextException`

### removeRole

    public void removeRole(String roleName)
                    throws PolicyContextException

  Used to remove a role and all its permissions from this PolicyConfiguration.

  Parameters:
    `roleName` - - the name of the Role to remove from this PolicyConfiguration.
  Throws:
    `SecurityException` - - when the caller does not have a SecurityPermission("setPolicy") permission.
    `UnsupportedOperationException` - - if the state of the policy context whose interface is this PolicyConfiguration Object is "deleted" or "inService" when this method is called.
    `PolicyContextException`

### removeUncheckedPolicy

    public void removeUncheckedPolicy()
                               throws PolicyContextException

  Used to remove any unchecked policy statements from this PolicyConfiguration.

  Throws:
    `SecurityException` - - when the caller does not have a SecurityPermission("setPolicy") permission.
    `UnsupportedOperationException` - - if the state of the policy context whose interface is this PolicyConfiguration Object is "deleted" or "inService" when this method is called.
    `PolicyContextException`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002 JBoss Group, LLC. All Rights Reserved.