Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

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:

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. Suppose the current thread traversed m callers, in the order of caller 1 to caller 2 to caller m. Then caller m invoked the checkPermission method. The checkPermission method determines whether access is granted or denied based on the following algorithm:

 i = m;
 
 while (i > 0) {
 
 	if (caller i's domain does not have the permission)
 		throw AccessControlException
 
 	else if (caller i is marked as privileged) {
 		if (a context was specified in the call to beginPrivileged) 
 			context.checkPermission(permission)
 		else
 			return;
 	}
 	i = i - 1;
 };

    // Next, 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.
 
 inheritedContext.checkPermission(permission);
 

A caller can be marked as being "privileged" (see beginPrivileged and below). When making access control decisions, the checkPermission method stops checking if it reaches a caller that was marked as "privileged" via a beginPrivileged call without a context argument (see below for information about a context argument). If that caller's 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 = 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)
 
 

There are also times where you don't know a priori which permissions to check the context against. In these cases you can use the beginPrivileged method that takes a context:

   somemethod() {
        ...normal code here...
        try {
           AccessController.beginPrivileged(acc);
           // Code goes here. Any permission checks from this
           // point forward require both the current context and
           // the snapshot's context to have the desired permission.
        } finally {
           AccessController.endPrivileged();
        }
     ...normal code here...
 

See Also:
AccessControlContext

Method Summary
static void  beginPrivileged()
Marks the calling thread's stack frame as "privileged".
static void  beginPrivileged(AccessControlContext context)
Marks the calling thread's stack frame as "privileged" and associates the given AccessControlContext with the privileged frame.
static void  checkPermission(Permission perm)
Determines whether the access request indicated by the specified permission should be allowed or denied, based on the security policy currently in effect.
static void  endPrivileged()
Unmarks the calling thread's stack frame, indicating it is no longer "privileged".
static AccessControlContext  getContext()
This method takes a "snapshot" of the current calling context, which includes the current Thread's inherited AccessControlContext, and places it in an AccessControlContext object.
 
Methods inherited from class java.lang.Object
 clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

beginPrivileged

public static void beginPrivileged()
Marks the calling thread's stack frame as "privileged".

beginPrivileged

public static void beginPrivileged(AccessControlContext context)
Marks the calling thread's stack frame as "privileged" and associates the given AccessControlContext with the privileged frame. The context will be included in all future access control checks, and will be checked after the privileged frame's ProtectionDomain is checked.

endPrivileged

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.

getContext

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 in 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

checkPermission

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.

Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Submit a bug or feature
Submit comments/suggestions about new javadoc look.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.