All Packages  Class Hierarchy  This Package  Previous  Next  Index  

Class java.security.AccessController

java.lang.Object
    |
    +----java.security.AccessController

public final class AccessController

extends Object

The AccessController class is used for three purposes, each of which is described in further detail below:

• to decide whether an access to a critical system resource is to be allowed or denied, based on the security policy currently in effect,

• to mark code as being "privileged", thus affecting subsequent access determinations, and

• to obtain a "snapshot" of the current calling context so access-control decisions from a different context can be made with respect to the saved context.

There is only one instance of AccessController in each Java runtime.

The checkPermission method determines whether the access request indicated by a specified permission should be granted or denied. A sample call appears below. In this example, checkPermission will determine whether or not to grant "read" access to the file named "testFile" in the "temp" directory.

 
   FilePermission perm = new FilePermission("temp/testFile", "read");
   AccessController.checkPermission(perm);
 
 

If a requested access is allowed, checkPermission returns quietly. If denied, an AccessControlException is thrown. AccessControlException can also be thrown if the requested permission is of an incorrect type or contains an invalid value. Such information is given whenever possible.

The checkPermission method determines whether access is granted or denied based on the following algorithm:

 
   for each domain on the stack {
          if (domain does not have permission)
                 throw AccessControlException
          else if (domain is marked as privileged)
                 return;
    }

    // if all of them allow access, then check the context inherited when
    // the thread was created. Whenever a new thread is created, the
    // AccessControlContext at that time is
    // stored and associated with the new thread, as the "inherited"
    // context.

   for each domain inherited from the thread that 
                               created the current thread {
          if (domain does not have permission)
                 throw AccessControlException
          else if (domain is marked as privileged)
                 return;
    }
    // if all of them allow access then return
    return;
 

A protection domain for a given thread at a given stack depth can be marked as being "privileged" (see beginPrivileged and below). When making access control decisions, the checkPermission method stops checking if it reaches a domain on the stack that is marked as "privileged". If that domain has the specified permission, no further checking is done and checkPermission returns quietly, indicating that the requested access is allowed. If that domain does not have the specified permission, an exception is thrown, as usual.

The normal use of the "privileged" feature is as follows. Note the use of the try/finally block to ensure the privileged section is always exited:

   somemethod() {
        ...normal code here...
        try {
           AccessController.beginPrivileged();
           // privileged code goes here, for example:
           System.loadLibrary("awt");
        } finally {
           AccessController.endPrivileged();
        }
     ...normal code here...
  }
 

Be *very* careful in your use of the "privileged" construct, and always remember to make the privileged code section as small as possible.

Note that checkPermission always performs security checks within the context of the currently executing thread. Sometimes a security check that should be made within a given context will actually need to be done from within a different context (for example, from within a worker thread). The getContext method and AccessControlContext class are provided for this situation. The getContext method takes a "snapshot" of the current calling context, and places it in an AccessControlContext object, which it returns. A sample call is the following:

 
   AccessControlContext acc = new AccessController.getContext()
 
 

AccessControlContext itself has a checkPermission method that makes access decisions based on the context it encapsulates, rather than that of the current execution thread. Code within a different context can thus call that method on the previously-saved AccessControlContext object. A sample call is the following:

 
   acc.checkPermission(permission)
 
 

See Also:

AccessControlContext

beginPrivileged()

Marks the calling thread's stack frame as "privileged".

checkPermission(Permission)

Determines whether the access request indicated by the specified permission should be allowed or denied, based on the security policy currently in effect.

endPrivileged()

Unmarks the calling thread's stack frame, indicating it is no longer "privileged".

getContext()

This method takes a "snapshot" of the current calling context, which includes the current Thread's inherited AccessControlContext, and places it an AccessControlContext object.

public static void beginPrivileged()

Marks the calling thread's stack frame as "privileged".

public static void endPrivileged()

Unmarks the calling thread's stack frame, indicating it is no longer "privileged". This call may only be done in the same frame as the beginPrivileged call.

public static AccessControlContext getContext()

This method takes a "snapshot" of the current calling context, which includes the current Thread's inherited AccessControlContext, and places it an AccessControlContext object. This context may then be checked at a later point, possibly in another thread.

Returns:

the AccessControlContext based on the current context.

See Also:

AccessControlContext

public static void checkPermission(Permission perm) throws AccessControlException

Determines whether the access request indicated by the specified permission should be allowed or denied, based on the security policy currently in effect. This method quietly returns if the access request is permitted, or throws a suitable AccessControlException otherwise.

Parameters:

perm - the requested permission.

Throws: AccessControlException

if the specified permission is not permitted, based on the current security policy.

All Packages  Class Hierarchy  This Package  Previous  Next  Index