net.jini.security.policy

Interface DynamicPolicy

All Known Implementing Classes:

AggregatePolicyProvider, DynamicPolicyProvider, LoaderSplitPolicyProvider

public interface DynamicPolicy

Interface implemented by security policy providers that may support dynamic granting of permissions at run-time. The grant methods of the Security class delegate to the methods declared by this interface when this interface is implemented by the installed security policy provider. Permissions are granted on the granularity of class loader; granting a permission requires (of the calling context) GrantPermission for that permission.

Since:

2.0

Author:

Sun Microsystems, Inc.

Method Summary

Modifier and Type	Method and Description
Permission[]	getGrants(Class cl, Principal[] principals) If this security policy provider supports dynamic permission grants, returns a new array containing the cumulative set of permissions dynamically granted to protection domains (including ones not yet created) that are associated with the class loader of the given class and possess at least the given set of principals.
void	grant(Class cl, Principal[] principals, Permission[] permissions) If this security policy provider supports dynamic permission grants, grants the specified permissions to all protection domains (including ones not yet created) that are associated with the class loader of the given class and possess at least the given set of principals.
boolean	grantSupported() Returns true if this policy provider supports dynamic permission grants; returns false otherwise.

Method Detail

grantSupported

boolean grantSupported()

Returns true if this policy provider supports dynamic permission grants; returns false otherwise. Note that this method may return different values for a given DynamicPolicy instance, depending on context. For example, a policy provider that delegates to different underlying policy implementations depending on thread state would return true from this method when the current delegate supports dynamic permission grants, but return false when another delegate lacking such support is in effect.

Returns:

true if policy supports dynamic permission grants under current context, false otherwise

grant

void grant(Class cl,
           Principal[] principals,
           Permission[] permissions)

If this security policy provider supports dynamic permission grants, grants the specified permissions to all protection domains (including ones not yet created) that are associated with the class loader of the given class and possess at least the given set of principals. If the given class is null, then the grant applies across all protection domains that possess at least the specified principals. If the list of principals is null or empty, then principals are effectively ignored in determining the protection domains to which the grant applies. If this policy provider does not support dynamic permission grants, then no permissions are granted and an UnsupportedOperationException is thrown.

The given class, if non-null, must belong to either the system domain or a protection domain whose associated class loader is non-null. If the class does not belong to such a protection domain, then no permissions are granted and an UnsupportedOperationException is thrown.

If a security manager is installed, its checkPermission method is called with a GrantPermission containing the permissions to grant; if the permission check fails, then no permissions are granted and the resulting SecurityException is thrown. The principals and permissions arrays passed in are neither modified nor retained; subsequent changes to the arrays have no effect on the grant operation.

Parameters:

cl - class to grant permissions to the class loader of, or null if granting across all class loaders

principals - if non-null, minimum set of principals to which grants apply

permissions - if non-null, permissions to grant

Throws:

UnsupportedOperationException - if policy does not support dynamic grants, or if cl is non-null and belongs to a protection domain with a null class loader other than the system domain

SecurityException - if a security manager is installed and the calling context does not have sufficient permissions to grant the given permissions

NullPointerException - if any element of the principals or permissions arrays is null

getGrants

Permission[] getGrants(Class cl,
                       Principal[] principals)

If this security policy provider supports dynamic permission grants, returns a new array containing the cumulative set of permissions dynamically granted to protection domains (including ones not yet created) that are associated with the class loader of the given class and possess at least the given set of principals. If the given class is null, then this method returns the cumulative set of permissions dynamically granted across all protection domains that possess at least the specified principals (i.e., through calls to the grant method where the specified class was null). If the list of principals is null or empty, then the permissions returned reflect only grants not qualified by principals (i.e., those performed through calls to the grant method where the specified principals array was null or empty). If this policy provider does not support dynamic permission grants, then an UnsupportedOperationException is thrown.

The given class, if non-null, must belong to either the system domain or a protection domain whose associated class loader is non-null. If the class does not belong to such a protection domain, then an UnsupportedOperationException is thrown.

Parameters:

cl - class to query the permissions dynamically granted to the class loader of, or null if querying permissions granted across all class loaders

principals - if non-null, principals to query dynamic grants for

Returns:

new array containing the permissions dynamically granted to the indicated class loader (if any) and principals

Throws:

UnsupportedOperationException - if policy does not support dynamic grants, or if cl is non-null and belongs to a protection domain with a null class loader other than the system domain

NullPointerException - if any element of the principals array is null