20.17 The Class java.lang.SecurityManager

public abstract class SecurityManager {
	protected boolean inCheck;
	protected SecurityManager()
throws SecurityException; protected Class[] getClassContext(); protected int classDepth(String name); protected boolean inClass(String name); protected ClassLoader currentClassLoader(); protected int classLoaderDepth(); protected boolean inClassLoader(); public boolean getInCheck(); public void checkCreateClassLoader()
throws SecurityException; public void checkAccess(Thread t)
throws SecurityException; public void checkAccess(ThreadGroup g)
throws SecurityException; public void checkExit(int status)
throws SecurityException; public void checkExec(String cmd)
throws SecurityException; public void checkPropertiesAccess()
throws SecurityException; public void checkPropertyAccess(String key)
throws SecurityException; public void checkLink(String libname)
throws SecurityException; public void checkRead(int fd)
throws SecurityException; public void checkRead(String file)
throws SecurityException; public void checkWrite(int fd)
throws SecurityException; public void checkWrite(String file)
throws SecurityException; public void checkDelete(String file)
throws SecurityException; public void checkConnect(String host, int port)
throws SecurityException; public void checkListen(int port)
throws SecurityException; public void checkAccept(String host, int port)
throws SecurityException; public void checkSetFactory()
throws SecurityException; public boolean checkTopLevelWindow()
throws SecurityException; public void checkPackageAccess(String packageName)
throws SecurityException; public void checkPackageDefinition(String packageName)
throws SecurityException; }

A running Java program may have a security manager, which is an instance of class SecurityManager. The current security manager is the one returned by the method invocation System.getSecurityManager() (§20.18.4).

The SecurityManager class contains a large number of methods whose names begin with "check". They are called by various methods throughout the Java libraries before those methods perform certain sensitive operations. The invocation of such a check method typically looks like this:


SecurityManager security = System.getSecurityManager();
if (security != null) {
	security.checkXXX(arguments);
}

The security manager is thereby given an opportunity to prevent completion of the operation by throwing an exception. The usual convention is that a security manager checking routine simply returns if the operation is permitted, or throws a SecurityException if the operation is not permitted. In one case, namely checkTopLevelWindow (§20.17.27), the checking routine must return a boolean value to indicate one of two levels of permission.

20.17.1 protected boolean inCheck = false;

By convention, this field should be assigned the value true whenever a security check is in progress. This matters when one of the checking routines needs to call outside code to do its work. Outside code can then use the method getInCheck (§20.17.9) to test the status of this flag.

20.17.2 protected SecurityManager()
throws SecurityException

This constructor checks to see whether a security manager has already been installed (§20.18.5); if so, creation of another security manager is not permitted, and so a SecurityException is thrown.

20.17.3 protected Class[] getClassContext()

This utility method for security managers scans the execution stack for the current thread and returns an array with one component for each stack frame. The component at position 0 corresponds to the top of the stack. If a component is a Class object, then the corresponding stack frame is for an invocation of a method of the class represented by that Class object.

20.17.4 protected int classDepth(String name)

This utility method for security managers searches the execution stack for the current thread to find the most recently invoked method whose execution has not yet completed and whose class has name as its fully qualified name. If such a method is found, its distance from the top of the stack is returned as a nonnegative integer; otherwise, -1 is returned.

20.17.5 protected boolean inClass(String name)

This utility method for security managers searches the execution stack for the current thread to find the most recently invoked method whose execution has not yet completed and whose class has name as its fully qualified name. If such a method is found, true is returned; otherwise, false is returned.

20.17.6 protected ClassLoader currentClassLoader()

This utility method for security managers searches the execution stack for the current thread to find the most recently invoked method whose execution has not yet completed and whose class was created by a class loader (§20.14). If such a method is found, a reference to the ClassLoader object for its class is returned; otherwise, null is returned.

20.17.7 protected int classLoaderDepth()

This utility method for security managers searches the execution stack for the current thread to find the most recently invoked method whose execution has not yet completed and whose class was created by a class loader (§20.14). If such a method is found, its distance from the top of the stack is returned as a nonnegative integer; otherwise, -1 is returned.

20.17.8 protected boolean inClassLoader()

This utility method for security managers searches the execution stack for the current thread to find the most recently invoked method whose execution has not yet completed and whose class was created by a class loader (§20.14). If such a method is found, true is returned; otherwise false is returned.

20.17.9 public boolean getInCheck()

The value of the inCheck field (§20.17.1) is returned.

20.17.10 public void checkCreateClassLoader()
throws SecurityException

The general contract of this method is that it should throw a SecurityException if creation of a class loader is not permitted.

This method is invoked for the current security manager (§20.18.4) by the constructor for class ClassLoader (§20.14.1).

The checkCreateClassLoader method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a class loader creation operation is to be permitted with a security manager installed.

20.17.11 public void checkAccess(Thread t)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if an operation that would modify the thread t is not permitted.

This method is invoked for the current security manager (§20.18.4) by method checkAccess (§20.20.12) of class Thread.

The checkAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a thread modification operation is to be permitted with a security manager installed.

20.17.12 public void checkAccess(ThreadGroup g)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if an operation that would modify the thread group g is not permitted.

This method is invoked for the current security manager (§20.18.4) by method checkAccess (§20.21.4) of class ThreadGroup.

The checkAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a thread group modification operation is to be permitted with a security manager installed.

20.17.13 public void checkExit(int status)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if an exit operation that would terminate the running Java Virtual Machine is not permitted.

This method is invoked for the current security manager (§20.18.4) by method exit (§20.16.2) of class Runtime.

The checkExit method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if the exit operation is to be permitted with a security manager installed.

20.17.14 public void checkExec(String cmd)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if a command exec operation is not permitted. The argument cmd is the name of the command to be executed.

This method is invoked for the current security manager (§20.18.4) by method exec (§20.16.6) of class Runtime.

The checkExec method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a command exec operation is to be permitted with a security manager installed.

20.17.15 public void checkPropertiesAccess()
throws SecurityException

The general contract of this method is that it should throw a SecurityException if getting or setting the system properties data structure is not permitted.

This method is invoked for the current security manager (§20.18.4) by the methods getProperties (§20.18.7) and setProperties (§20.18.8) of class System.

The checkPropertiesAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a properties access operation is to be permitted with a security manager installed.

20.17.16 public void checkPropertyAccess(String key)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if getting the value of the system property named by the key is not permitted.

This method is invoked for the current security manager (§20.18.4) by the methods getProperty of one argument (§20.18.9) and getProperty of two arguments (§20.18.10) of class System.

The checkPropertyAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if accessing the value of a system property is to be permitted with a security manager installed.

20.17.17 public void checkLink(String libname)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if dynamic linking of the specified library code file is not permitted. The argument may be a simple library name or a complete file name.

This method is invoked for the current security manager (§20.18.4) by methods load (§20.16.14) and loadLibrary (§20.16.13) of class Runtime.

The checkLink method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a dynamic code linking operation is to be permitted with a security manager installed.

20.17.18 public void checkRead(int fd)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if creating an input stream using the specified file descriptor is not permitted.

This method is invoked for the current security manager (§20.18.4) by one constructor for java.io.FileInputStream (§22.4.3).

The checkRead method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if creating an input stream from an existing file descriptor is to be permitted with a security manager installed.

20.17.19 public void checkRead(String file)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if reading the specified file or directory, or examining associated file-system information, or testing for its existence, is not permitted.

This method is invoked for the current security manager (§20.18.4) by two constructors for java.io.FileInputStream (§22.4.1, §22.4.2); by two constructors for java.io.RandomAccessFile (§22.23.1, §22.23.2); and by methods exists (§22.24.16), canRead (§22.24.17), isFile (§22.24.19), isDirectory (§22.24.20), lastModified (§22.24.21), length (§22.24.22), list with no arguments (§22.24.25), and list with one argument (§22.24.26) of the class java.io.File.

The checkRead method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if read access to a file is to be permitted with a security manager installed.

20.17.20 public void checkWrite(int fd)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if creating an output stream using the specified file descriptor is not permitted.

This method is invoked for the current security manager (§20.18.4) by one constructor for java.io.FileOutputStream (§22.16.3).

The checkWrite method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if creating an output stream from an existing file descriptor is to be permitted with a security manager installed.

20.17.21 public void checkWrite(String file)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if writing, modifying, creating (for output), or renaming the specified file or directory is not permitted.

This method is invoked for the current security manager (§20.18.4) by two constructors for java.io.FileOutputStream (§22.16.1, §22.16.2); by two constructors for java.io.RandomAccessFile (§22.23.1, §22.23.2); and by methods canWrite (§22.24.18), mkdir (§22.24.23), and renameTo (§22.24.27) of class java.io.File.

The checkWrite method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if write access to a file is to be permitted with a security manager installed.

20.17.22 public void checkDelete(String file)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if deleting the specified file is not permitted.

This method is invoked for the current security manager (§20.18.4) by method delete (§22.24.28) of class java.io.File.

The checkDelete method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a file deletion operation is to be permitted with a security manager installed.

20.17.23 public void checkConnect(String host, int port)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if connecting to the indicated port of the indicated network host is not permitted.

This method is invoked for the current security manager (§20.18.4) by two constructors for class java.net.Socket, methods send and receive of class java.net.DatagramSocket, and methods getByName and getAllByName of class java.net.InetAddress. (These classes are not documented in this specification. See The Java Application Programming Interface.)

The checkConnect method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a network connection is to be permitted with a security manager installed.

20.17.24 public void checkListen(int port)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if listening to the specified local network port is not permitted.

This method is invoked for the current security manager (§20.18.4) by the constructor of one argument for class java.net.DatagramSocket and by the constructors for class java.net.ServerSocket. (These classes are not documented in this specification. See The Java Application Programming Interface.)

The checkListen method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if listening to a local network port is to be permitted with a security manager installed.

20.17.25 public void checkAccept(String host, int port)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if accepting a connection from the indicated port of the indicated network host is not permitted.

This method is invoked for the current security manager (§20.18.4) by method accept of class java.net.ServerSocket. (This class is not documented in this specification. See The Java Application Programming Interface.)

The checkAccept method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if accepting a network connection is to be permitted with a security manager installed.

20.17.26 public void checkSetFactory()
throws SecurityException

The general contract of this method is that it should throw a SecurityException if installing a "factory" for a socket, server socket, URL, or URL connection is not permitted.

This method is invoked for the current security manager (§20.18.4) by:

	method setSocketFactory of class java.net.ServerSocket
	method setSocketImplFactory of class java.net.Socket
	method setURLStreamHandlerFactory of class java.net.URL
	method setContentHandlerFactory of class java.net.URLConnection

(These classes are not documented in this specification. See The Java Application Programming Interface.)

The checkSetFactory method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if a factory installation operation is to be permitted with a security manager installed.

20.17.27 public boolean checkTopLevelWindow()
throws SecurityException

The general contract of this method is that it should throw a SecurityException if creation of a top-level window is not permitted. If creation of a top-level window is permitted, then this method should return false if the window ought to bear a clear warning that it is a window for an executable applet. A returned value of true means that the security manager places no restriction on window creation.

This method is invoked for the current security manager (§20.18.4) by the constructors for class java.awt.Window. (This class is not documented in this specification. See The Java Application Programming Interface.)

The checkTopLevelWindow method defined by class SecurityManager always returns false. A subclass must override this method if a window creation operation is to be unrestricted or forbidden with a security manager installed.

20.17.28 public void checkPackageAccess(String packageName)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if the current applet is not permitted to access the package named by the argument. This method is intended for use by Java-capable web browsers.

The checkPackageAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if package access by an applet is to be permitted with a security manager installed.

20.17.29 public void checkPackageDefinition(String packageName)
throws SecurityException

The general contract of this method is that it should throw a SecurityException if the current applet is not permitted to define a class (or interface) in the package named by the argument. This method is intended for use by Java-capable web browsers.

The checkPackageAccess method defined by class SecurityManager always throws a SecurityException. A subclass must override this method if class definition by an applet is to be permitted with a security manager installed.