Return-Path: Delivered-To: apmail-harmony-commits-archive@www.apache.org Received: (qmail 62729 invoked from network); 2 May 2009 08:11:41 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 2 May 2009 08:11:41 -0000 Received: (qmail 43023 invoked by uid 500); 2 May 2009 08:11:41 -0000 Delivered-To: apmail-harmony-commits-archive@harmony.apache.org Received: (qmail 42958 invoked by uid 500); 2 May 2009 08:11:40 -0000 Mailing-List: contact commits-help@harmony.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@harmony.apache.org Delivered-To: mailing list commits@harmony.apache.org Received: (qmail 42949 invoked by uid 99); 2 May 2009 08:11:40 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 02 May 2009 08:11:40 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 02 May 2009 08:11:36 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 652282388CF8; Sat, 2 May 2009 08:10:52 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r770909 [6/10] - in /harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang: ./ ref/ reflect/ Date: Sat, 02 May 2009 08:09:57 -0000 To: commits@harmony.apache.org From: tellison@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090502081052.652282388CF8@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/RuntimePermission.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/RuntimePermission.java?rev=770909&r1=770908&r2=770909&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/RuntimePermission.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/RuntimePermission.java Sat May 2 08:09:50 2009 @@ -20,7 +20,9 @@ import java.security.BasicPermission; /** - * RuntimePermission objects represent access to runtime support. + * Represents the permission to execute a runtime-related function. There is no + * action list associated with a {@code RuntimePermission}; the user either has + * the permission or he doesn't. */ public final class RuntimePermission extends BasicPermission { @@ -75,25 +77,23 @@ "setContextClassLoader"); //$NON-NLS-1$ /** - * Creates an instance of this class with the given name. - * + * Creates an instance of {@code RuntimePermission} with the specified name. * * @param permissionName - * String the name of the new permission. + * the name of the new permission. */ public RuntimePermission(String permissionName) { super(permissionName); } /** - * Creates an instance of this class with the given name and action list. - * The action list is ignored. - * + * Creates an instance of {@code RuntimePermission} with the specified name + * and action list. The action list is ignored. * * @param name - * String the name of the new permission. + * the name of the new permission. * @param actions - * String ignored. + * ignored. */ public RuntimePermission(String name, String actions) { super(name, actions); Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SecurityException.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SecurityException.java?rev=770909&r1=770908&r2=770909&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SecurityException.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SecurityException.java Sat May 2 08:09:50 2009 @@ -17,36 +17,40 @@ package java.lang; - /** - * This runtime exception is thrown when a security manager check fails. + * Thrown when a security manager check fails. */ public class SecurityException extends java.lang.RuntimeException { - private static final long serialVersionUID = 6878364983674394167L; + private static final long serialVersionUID = 6878364983674394167L; - /** - * Constructs a new instance of this class with its walkback filled in. - */ - public SecurityException() { - super(); - } + /** + * Constructs a new {@code SecurityException} that includes the current + * stack trace. + */ + public SecurityException() { + super(); + } - /** - * Constructs a new instance of this class with its walkback and message - * filled in. - * - * @param detailMessage - * String The detail message for the exception. - */ - public SecurityException(String detailMessage) { - super(detailMessage); - } + /** + * Constructs a new {@code SecurityException} with the current stack trace + * and the specified detail message. + * + * @param detailMessage + * the detail message for this exception. + */ + public SecurityException(String detailMessage) { + super(detailMessage); + } /** - *

Constructs a new instance with a message and cause.

- * @param message The message to assign to this exception. - * @param cause The optional cause of this exception; may be null. + * Constructs a new {@code SecurityException} with the current stack trace, + * the specified detail message and the specified cause. + * + * @param message + * the detail message for this exception. + * @param cause + * the optional cause of this exception, may be {@code null}. * @since 1.5 */ public SecurityException(String message, Throwable cause) { @@ -54,8 +58,11 @@ } /** - *

Constructs a new instance with a cause.

- * @param cause The optional cause of this exception; may be null. + * Constructs a new {@code SecurityException} with the current stack trace + * and the specified cause. + * + * @param cause + * the optional cause of this exception, may be {@code null}. * @since 1.5 */ public SecurityException(Throwable cause) { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SecurityManager.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SecurityManager.java?rev=770909&r1=770908&r2=770909&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SecurityManager.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/SecurityManager.java Sat May 2 08:09:50 2009 @@ -37,8 +37,14 @@ import org.apache.harmony.luni.util.PriviAction; /** - * SecurityManager is the abstract superclass of the classes which can provide - * security verification for a running program. + * Provides security verification facilities for applications. {@code + * SecurityManager} contains a set of {@code checkXXX} methods which determine + * if it is safe to perform a specific operation such as establishing network + * connections, modifying files, and many more. In general, these methods simply + * return if they allow the application to perform the operation; if an + * operation is not allowed, then they throw a {@link SecurityException}. The + * only exception is {@link #checkTopLevelWindow(Object)}, which returns a + * boolean to indicate permission. */ public class SecurityManager { @@ -52,13 +58,16 @@ /** * Flag to indicate whether a security check is in progress. * - * @deprecated Use checkPermission + * @deprecated Use {@link #checkPermission} */ @Deprecated protected boolean inCheck; /** - * Constructs a new instance of this class. + * Constructs a new {@code SecurityManager} instance. + *

+ * The {@code RuntimePermission("createSecurityManager")} is checked if a + * security manager is installed. */ public SecurityManager() { SecurityManager security = System.getSecurityManager(); @@ -73,13 +82,18 @@ } /** - * Checks whether the running program is allowed to accept socket + * Checks whether the calling thread is allowed to accept socket * connections. * * @param host - * the address of the host which is attempting to connect + * the address of the host that attempts to connect. * @param port - * the port number to check + * the port number to check. + * @throws NullPointerException + * if {@code host} is {@code null}. + * @throws SecurityException + * if the calling thread is not allowed to accept socket + * connections from {@code host} through {@code port}. */ public void checkAccept(String host, int port) { if (host == null) { @@ -89,10 +103,13 @@ } /** - * Checks whether the running program is allowed to modify the thread. + * Checks whether the calling thread is allowed to modify the specified + * thread. * * @param thread - * the thread we are attempting to modify + * the thread to access. + * @throws SecurityException + * if the calling thread is not allowed to access {@code thread}. */ public void checkAccess(Thread thread) { // Only worry about system threads. Dead threads have a null group. @@ -103,11 +120,15 @@ } /** - * Checks whether the running program is allowed to modify the thread group. - * + * Checks whether the calling thread is allowed to modify the specified + * thread group. * * @param group - * the thread group we are attempting to modify + * the thread group to access. + * @throws NullPointerException + * if {@code group} is {@code null}. + * @throws SecurityException + * if the calling thread is not allowed to access {@code group}. */ public void checkAccess(ThreadGroup group) { // Only worry about system threads. @@ -120,14 +141,19 @@ } /** - * Checks whether the running program is allowed to establish socket + * Checks whether the calling thread is allowed to establish socket * connections. A -1 port indicates the caller is trying to resolve the * hostname. * * @param host - * String the address of the host to connect to. + * the address of the host to connect to. * @param port - * int the port number to check, or -1 for resolve. + * the port number to check, or -1 for resolve. + * @throws NullPointerException + * if {@code host} is {@code null}. + * @throws SecurityException + * if the calling thread is not allowed to connect to {@code + * host} through {@code port}. */ public void checkConnect(String host, int port) { if (host == null) { @@ -141,16 +167,21 @@ } /** - * Checks whether the given security context is allowed to establish socket - * connections. A -1 port indicates the caller is trying to resolve the - * hostname. + * Checks whether the specified security context is allowed to establish + * socket connections. A -1 port indicates the caller is trying to resolve + * the hostname. * * @param host - * String the address of the host to connect to. + * the address of the host to connect to. * @param port - * int the port number to check, or -1 for resolve. + * the port number to check, or -1 for resolve. * @param context - * Object the security context to use for the check. + * the security context to use for the check. + * @throws NullPointerException + * if {@code host} is {@code null}. + * @throws SecurityException + * if {@code context} is not allowed to connect to {@code host} + * through {@code port}. */ public void checkConnect(String host, int port, Object context) { if (port > 0) { @@ -162,29 +193,37 @@ } /** - * Checks whether the running program is allowed to create a class loader. + * Checks whether the calling thread is allowed to create a class loader. + * + * @throws SecurityException + * if the calling thread is not allowed to create a class + * loader. */ public void checkCreateClassLoader() { checkPermission(RuntimePermission.permissionToCreateClassLoader); } /** - * Checks whether the running program is allowed to delete the file named by - * the argument, which should be passed in canonical form. + * Checks whether the calling thread is allowed to delete the file with the + * specified name, which should be passed in canonical form. * * @param file - * the name of the file to check + * the name of the file to delete. + * @throws SecurityException + * if the calling thread is not allowed to delete {@code file}. */ public void checkDelete(String file) { checkPermission(new FilePermission(file, "delete")); //$NON-NLS-1$ } /** - * Checks whether the running program is allowed to execute the specified + * Checks whether the calling thread is allowed to execute the specified * platform specific command. * * @param cmd - * the command line + * the command line to execute. + * @throws SecurityException + * if the calling thread is not allowed to execute {@code cmd}. */ public void checkExec(String cmd) { checkPermission(new FilePermission(new File(cmd).isAbsolute() ? cmd @@ -192,21 +231,28 @@ } /** - * Checks whether the running program is allowed to terminate itself. + * Checks whether the calling thread is allowed to terminate the virtual + * machine. * * @param status - * the status to return from the exit. + * the status that the virtual machine returns when it is + * terminated. + * @throws SecurityException + * if the calling thread is not allowed to terminate the virtual + * machine with {@code status}. */ public void checkExit(int status) { checkPermission(RuntimePermission.permissionToExitVM); } /** - * Checks whether the running program is allowed to load the specified - * native library. + * Checks whether the calling thread is allowed to load the specified native + * library. * * @param libName - * the name of the library to load + * the name of the library to load. + * @throws SecurityException + * if the calling thread is not allowed to load {@code libName}. */ public void checkLink(String libName) { if (libName == null) { @@ -216,11 +262,13 @@ } /** - * Checks whether the running program is allowed to listen on the specified + * Checks whether the calling thread is allowed to listen on the specified * port. * * @param port - * int the port number to check + * the port number to check. + * @throws SecurityException + * if the calling thread is not allowed listen on {@code port}. */ public void checkListen(int port) { if (port == 0) { @@ -231,18 +279,23 @@ } /** - * Checks whether the running program is allowed to access members. The - * default is to allow access to public members (i.e. - * java.lang.reflect.PUBLIC) and to classes loaded by the same loader as the - * original caller (i.e. the method that called the reflect API). - * - * Due to the nature of the check, overriding implementations cannot call - * super.checkMemberAccess() since the stack would no longer be of the - * expected shape. + * Checks whether the calling thread is allowed to access members. The + * default is to allow access to public members (that is, {@code + * java.lang.reflect.Member.PUBLIC}) and to classes loaded by the same + * loader as the original caller (that is, the method that called the + * reflect API). Due to the nature of the check, overriding implementations + * cannot call {@code super.checkMemberAccess()} since the stack would no + * longer be of the expected shape. * - * @param cls ? + * @param cls + * the class of which members are accessed. * @param type - * Either java.lang.reflect.Member.PUBLIC or DECLARED + * the access type, either {@code + * java.lang.reflect.Member.PUBLIC} or {@code + * java.lang.reflect.Member.DECLARED}. + * @throws SecurityException + * if the calling thread is not allowed to access members of + * {@code cls}. */ public void checkMemberAccess(Class cls, int type) { if (cls == null) { @@ -270,8 +323,13 @@ } /** - * Checks whether the running program is allowed to join, leave or send to a - * multicast address. + * Checks whether the calling thread is allowed to use the specified IP + * multicast group address. + * + * @param maddr + * the internet group address to use. + * @throws SecurityException + * if the calling thread is not allowed to use {@code maddr}. */ public void checkMulticast(InetAddress maddr) { checkPermission(new SocketPermission(maddr.getHostAddress(), @@ -279,10 +337,17 @@ } /** - * Checks whether the running program is allowed to join, leave or send to a - * multicast address. + * Checks whether the calling thread is allowed to use the specified IP + * multicast group address. * - * @deprecated use SecurityManager#checkMulticast(java.net.InetAddress) + * @param maddr + * the internet group address to use. + * @param ttl + * the value in use for multicast send. This parameter is + * ignored. + * @throws SecurityException + * if the calling thread is not allowed to use {@code maddr}. + * @deprecated use {@link #checkMulticast(java.net.InetAddress)} */ @Deprecated public void checkMulticast(InetAddress maddr, byte ttl) { @@ -291,11 +356,14 @@ } /** - * Checks whether the running program is allowed to access the specified + * Checks whether the calling thread is allowed to access the specified * package. * * @param packageName - * the name of the package to be accessed. + * the name of the package to access. + * @throws SecurityException + * if the calling thread is not allowed to access {@code + * packageName}. */ public void checkPackageAccess(String packageName) { if (packageName == null) { @@ -308,11 +376,14 @@ } /** - * Checks whether the running program is allowed to define new classes in - * the specified package. + * Checks whether the calling thread is allowed to define new classes in the + * specified package. * * @param packageName * the name of the package to add a class to. + * @throws SecurityException + * if the calling thread is not allowed to add classes to + * {@code packageName}. */ public void checkPackageDefinition(String packageName) { if (packageName == null) { @@ -355,30 +426,39 @@ } /** - * Checks whether the running program is allowed to access the system + * Checks whether the calling thread is allowed to access the system * properties. + * + * @throws SecurityException + * if the calling thread is not allowed to access system + * properties. */ public void checkPropertiesAccess() { checkPermission(READ_WRITE_ALL_PROPERTIES_PERMISSION); } /** - * Checks whether the running program is allowed to access a particular + * Checks whether the calling thread is allowed to access a particular * system property. * * @param key - * the name of the property to be accessed. + * the name of the property to access. + * @throws SecurityException + * if the calling thread is not allowed to access the {@code + * key} system property. */ public void checkPropertyAccess(String key) { checkPermission(new PropertyPermission(key, "read")); //$NON-NLS-1$ } /** - * Checks whether the running program is allowed to read from the file whose - * descriptor is the argument. + * Checks whether the calling thread is allowed to read from the file with + * the specified file descriptor. * * @param fd - * the file descriptor of the file to check + * the file descriptor of the file to read from. + * @throws SecurityException + * if the calling thread is not allowed to read from {@code fd}. */ public void checkRead(FileDescriptor fd) { if (fd == null) { @@ -388,11 +468,14 @@ } /** - * Checks whether the running program is allowed to read from the file named - * by the argument, which should be passed in canonical form. + * Checks whether the calling thread is allowed to read from the file with + * the specified name, which should be passed in canonical form. * * @param file - * String the name of the file or directory to check. + * the name of the file or directory to read from. + * @throws SecurityException + * if the calling thread is not allowed to read from {@code + * file}. */ public void checkRead(String file) { checkPermission(new FilePermission(file, "read")); //$NON-NLS-1$ @@ -403,39 +486,52 @@ * file named by the argument, which should be passed in canonical form. * * @param file - * String the name of the file or directory to check. + * the name of the file or directory to check. * @param context - * Object the security context to use for the check. + * the security context to use for the check. + * @throws SecurityException + * if {@code context} is not allowed to read from {@code file}. */ public void checkRead(String file, Object context) { checkPermission(new FilePermission(file, "read"), context); //$NON-NLS-1$ } /** - * Checks whether the running program is allowed to perform the security + * Checks whether the calling thread is allowed to perform the security * operation named by the target. * * @param target - * String the name of the operation to perform. + * the name of the operation to perform. + * @throws SecurityException + * if the calling thread is not allowed to perform + * {@code target}. */ public void checkSecurityAccess(String target) { checkPermission(new SecurityPermission(target)); } /** - * Checks whether the running program is allowed to set the net object + * Checks whether the calling thread is allowed to set the net object * factories. + * + * @throws SecurityException + * if the calling thread is not allowed to set the net object + * factories. */ public void checkSetFactory() { checkPermission(RuntimePermission.permissionToSetFactory); } /** - * Checks whether the running program is allowed to create a top level - * window. + * Checks whether the calling thread is trusted to show the specified top + * level window. * * @param window - * The non-null window for which to check access + * the window to show. + * @return {@code true} if the calling thread is allowed to show {@code + * window}; {@code false} otherwise. + * @throws NullPointerException + * if {@code window} is {@code null}. */ public boolean checkTopLevelWindow(Object window) { if (window == null) { @@ -460,8 +556,12 @@ } /** - * Checks whether the running program is allowed to access the system + * Checks whether the calling thread is allowed to access the system * clipboard. + * + * @throws SecurityException + * if the calling thread is not allowed to access the system + * clipboard. */ public void checkSystemClipboardAccess() { try { @@ -481,8 +581,12 @@ } /** - * Checks whether the running program is allowed to access the AWT Event - * queue. Since we don't support AWT, the answer is no. + * Checks whether the calling thread is allowed to access the AWT event + * queue. + * + * @throws SecurityException + * if the calling thread is not allowed to access the AWT event + * queue. */ public void checkAwtEventQueueAccess() { try { @@ -502,18 +606,24 @@ } /** - * Checks whether the running program is allowed to start a new print job. + * Checks whether the calling thread is allowed to start a new print job. + * + * @throws SecurityException + * if the calling thread is not allowed to start a new print + * job. */ public void checkPrintJobAccess() { checkPermission(RuntimePermission.permissionToQueuePrintJob); } /** - * Checks whether the running program is allowed to read from the file whose - * descriptor is the argument. + * Checks whether the calling thread is allowed to write to the file with + * the specified file descriptor. * * @param fd - * the file descriptor of the file to check + * the file descriptor of the file to write to. + * @throws SecurityException + * if the calling thread is not allowed to write to {@code fd}. */ public void checkWrite(FileDescriptor fd) { if (fd == null) { @@ -523,22 +633,25 @@ } /** - * Checks whether the running program is allowed to write to the file named - * by the argument, which should be passed in canonical form. + * Checks whether the calling thread is allowed to write to the file with + * the specified name, which should be passed in canonical form. * * @param file - * the name of the file to check + * the name of the file or directory to write to. + * @throws SecurityException + * if the calling thread is not allowed to write to + * {@code file}. */ public void checkWrite(String file) { checkPermission(new FilePermission(file, "write")); //$NON-NLS-1$ } /** - * Answers true if the security manager is currently checking something. + * Indicates if this security manager is currently checking something. * - * @return boolean true if we are are in a security check method. - * - * @deprecated Use checkPermission + * @return {@code true} if this security manager is executing a security + * check method; {@code false} otherwise. + * @deprecated Use {@link #checkPermission}. */ @Deprecated public boolean getInCheck() { @@ -546,11 +659,11 @@ } /** - * Answers an array containing one entry for each method in the stack. Each - * entry is the java.lang.Class which represents the class in which the - * method is defined. + * Returns an array containing one entry for each method in the current + * execution stack. Each entry is the {@code java.lang.Class} which + * represents the class in which the method is defined. * - * @return Class[] all of the classes in the stack. + * @return all classes in the execution stack. */ @SuppressWarnings("unchecked") protected Class[] getClassContext() { @@ -558,12 +671,11 @@ } /** - * Answers the class loader of the first class in the stack whose class - * loader is not a system class loader. - * - * @return ClassLoader the most recent non-system class loader. + * Returns the class loader of the first class in the execution stack whose + * class loader is not a system class loader. * - * @deprecated Use checkPermission + * @return the most recent non-system class loader. + * @deprecated Use {@link #checkPermission}. */ @Deprecated protected ClassLoader currentClassLoader() { @@ -594,13 +706,12 @@ } /** - * Answers the index in the stack of three first class whose class loader is - * not a system class loader. - * - * @return int the frame index of the first method whose class was loaded by - * a non-system class loader. + * Returns the index in the call stack of the first class whose class loader + * is not a system class loader. * - * @deprecated Use checkPermission + * @return the frame index of the first method whose class was loaded by a + * non-system class loader. + * @deprecated Use {@link #checkPermission}. */ @Deprecated protected int classLoaderDepth() { @@ -630,12 +741,11 @@ } /** - * Answers the first class in the stack which was loaded by a class loader - * which is not a system class loader. + * Returns the first class in the call stack that was loaded by a class + * loader which is not a system class loader. * - * @return Class the most recent class loaded by a non-system class loader. - * - * @deprecated Use checkPermission + * @return the most recent class loaded by a non-system class loader. + * @deprecated Use {@link #checkPermission}. */ @Deprecated protected Class currentLoadedClass() { @@ -665,15 +775,15 @@ } /** - * Answers the index in the stack of the first method which is contained in - * a class called name. If no methods from this class are in - * the stack, return -1. + * Returns the index in the call stack of the first method which is + * contained in the class with the specified name. Returns -1 if no methods + * from this class are in the stack. * * @param name - * String the name of the class to look for. - * @return int the depth in the stack of a the first method found. - * - * @deprecated Use checkPermission + * the name of the class to look for. + * @return the frame index of the first method found is contained in the + * class identified by {@code name}. + * @deprecated Use {@link #checkPermission}. */ @Deprecated protected int classDepth(String name) { @@ -687,14 +797,14 @@ } /** - * Answers true if there is a method on the stack from the specified class, - * and false otherwise. + * Indicates whether there is a method in the call stack from the class with + * the specified name. * * @param name - * String the name of the class to look for. - * @return boolean true if we are running a method from the specified class. - * - * @deprecated Use checkPermission + * the name of the class to look for. + * @return {@code true} if a method from the class identified by {@code + * name} is executing; {@code false} otherwise. + * @deprecated Use {@link #checkPermission}. */ @Deprecated protected boolean inClass(String name) { @@ -702,12 +812,12 @@ } /** - * Answers true if there is a method on the stack from a class which was - * defined by a non-system classloader. + * Indicates whether there is a method in the call stack from a class which + * was defined by a non-system class loader. * - * @return boolean - * - * @deprecated Use checkPermission + * @return {@code true} if a method from a class that was defined by a + * non-system class loader is executing; {@code false} otherwise. + * @deprecated Use {@link #checkPermission} */ @Deprecated protected boolean inClassLoader() { @@ -715,30 +825,37 @@ } /** - * Answers the thread group which should be used to instantiate new threads. + * Returns the thread group which should be used to instantiate new threads. * By default, this is the same as the thread group of the thread running * this method. * - * @return ThreadGroup The thread group to create new threads in. + * @return ThreadGroup the thread group to create new threads in. */ public ThreadGroup getThreadGroup() { return Thread.currentThread().getThreadGroup(); } /** - * Answers an object which encapsulates the security state of the current - * point in the execution. In our case, this is an AccessControlContext. + * Returns an object which encapsulates the security state of the current + * point in the execution. In our case, this is an {@link + * java.security.AccessControlContext}. + * + * @return an object that encapsulates information about the current + * execution environment. */ public Object getSecurityContext() { return AccessController.getContext(); } /** - * Checks whether the running program is allowed to access the resource - * being guarded by the given Permission argument. - * + * Checks whether the calling thread is allowed to access the resource being + * guarded by the specified permission object. + * * @param permission - * the permission to check + * the permission to check. + * @throws SecurityException + * if the requested {@code permission} is denied according to + * the current security policy. */ public void checkPermission(Permission permission) { try { @@ -750,11 +867,18 @@ } /** - * Checks whether the running program is allowed to access the resource - * being guarded by the given Permission argument. + * Checks whether the specified security context is allowed to access the + * resource being guarded by the specified permission object. * * @param permission - * the permission to check + * the permission to check. + * @param context + * the security context for which to check permission. + * @throws SecurityException + * if {@code context} is not an instance of {@code + * AccessControlContext} or if the requested {@code permission} + * is denied for {@code context} according to the current + * security policy. */ public void checkPermission(Permission permission, Object context) { try { Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Short.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Short.java?rev=770909&r1=770908&r2=770909&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Short.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/Short.java Sat May 2 08:09:50 2009 @@ -18,9 +18,7 @@ package java.lang; /** - *

- * Short is the wrapper for the primitive type short. - *

+ * The wrapper for the primitive type {@code short}. * * @see java.lang.Number * @since 1.1 @@ -29,38 +27,33 @@ private static final long serialVersionUID = 7515723908773894738L; - /** + /** * The value which the receiver represents. */ private final short value; /** - *

- * Constant for the maximum short value, 215-1. - *

+ * Constant for the maximum {@code short} value, 215-1. */ public static final short MAX_VALUE = (short) 0x7FFF; /** - *

- * Constant for the minimum short value, -215. - *

+ * Constant for the minimum {@code short} value, -215. */ public static final short MIN_VALUE = (short) 0x8000; /** - *

- * Constant for the number of bits to represent a short in - * two's compliment form. - *

- * + * Constant for the number of bits needed to represent a {@code short} in + * two's complement form. + * * @since 1.5 */ public static final int SIZE = 16; - /** - * The java.lang.Class that represents this class. - */ + /** + * The {@link Class} object that represents the primitive type {@code + * short}. + */ @SuppressWarnings("unchecked") public static final Class TYPE = (Class) new short[0] .getClass().getComponentType(); @@ -69,70 +62,66 @@ // defined to be "java.lang.Short.TYPE"; - /** - * Constructs a new instance of this class given a string. - * - * @param string - * a string representation of a short quantity. - * @exception NumberFormatException - * if the argument could not be parsed as a short quantity. - */ + /** + * Constructs a new {@code Short} from the specified string. + * + * @param string + * the string representation of a short value. + * @throws NumberFormatException + * if {@code string} can not be decoded into a short value. + * @see #parseShort(String) + */ public Short(String string) throws NumberFormatException { this(parseShort(string)); } - /** - * Constructs a new instance of the receiver which represents the short - * valued argument. - * - * @param value - * the short to store in the new instance. - */ + /** + * Constructs a new {@code Short} with the specified primitive short value. + * + * @param value + * the primitive short value to store in the new instance. + */ public Short(short value) { this.value = value; } - /** - * Answers the byte value which the receiver represents - * - * @return byte the value of the receiver. - */ @Override public byte byteValue() { return (byte) value; } /** - *

- * Compares this Short to the Short - * passed. If this instance's value is equal to the value of the instance - * passed, then 0 is returned. If this instance's value is less than the - * value of the instance passed, then a negative value is returned. If this - * instance's value is greater than the value of the instance passed, then a - * positive value is returned. - *

+ * Compares this object to the specified short object to determine their + * relative order. * - * @param object The instance to compare to. - * @throws NullPointerException if object is - * null. + * @param object + * the short object to compare this object to. + * @return a negative value if the value of this short is less than the + * value of {@code object}; 0 if the value of this short and the + * value of {@code object} are equal; a positive value if the value + * of this short is greater than the value of {@code object}. + * @throws NullPointerException + * if {@code object} is null. + * @see java.lang.Comparable * @since 1.2 */ public int compareTo(Short object) { return value > object.value ? 1 : (value < object.value ? -1 : 0); } - /** - * Parses the string argument as if it was a short value and returns the - * result. Throws NumberFormatException if the string does not represent an - * int quantity. The string may be a hexadecimal ("0x..."), octal ("0..."), - * or decimal ("...") representation of a byte. - * - * @param string - * a string representation of a short quantity. - * @return Short the value represented by the argument - * @exception NumberFormatException - * if the argument could not be parsed as a short quantity. - */ + /** + * Parses the specified string and returns a {@code Short} instance if the + * string can be decoded into a short value. The string may be an optional + * minus sign "-" followed by a hexadecimal ("0x..." or "#..."), octal + * ("0..."), or decimal ("...") representation of a short. + * + * @param string + * a string representation of a short value. + * @return a {@code Short} containing the value represented by + * {@code string}. + * @throws NumberFormatException + * if {@code string} can not be parsed as a short value. + */ public static Short decode(String string) throws NumberFormatException { int intValue = Integer.decode(string).intValue(); short result = (short) intValue; @@ -142,108 +131,78 @@ throw new NumberFormatException(); } - /** - * Answers the double value which the receiver represents - * - * @return double the value of the receiver. - */ @Override public double doubleValue() { return value; } - /** - * Compares the argument to the receiver, and answers true if they represent - * the same object using a class specific comparison. - *

- * In this case, the argument must also be a Short, and the receiver and - * argument must represent the same short value. - * - * @param object - * the object to compare with this object - * @return true if the object is the same as this object - * false if it is different from this object - * @see #hashCode - */ + /** + * Compares this instance with the specified object and indicates if they + * are equal. In order to be equal, {@code object} must be an instance of + * {@code Short} and have the same short value as this object. + * + * @param object + * the object to compare this short with. + * @return {@code true} if the specified object is equal to this + * {@code Short}; {@code false} otherwise. + */ @Override public boolean equals(Object object) { return (object instanceof Short) && (value == ((Short) object).value); } - /** - * Answers the float value which the receiver represents - * - * @return float the value of the receiver. - */ @Override public float floatValue() { return value; } - /** - * Answers an integer hash code for the receiver. Any two objects which - * answer true when passed to equals must - * answer the same value for this method. - * - * @return the receiver's hash - * - * @see #equals - */ @Override public int hashCode() { return value; } - /** - * Answers the int value which the receiver represents - * - * @return int the value of the receiver. - */ @Override public int intValue() { return value; } - /** - * Answers the long value which the receiver represents - * - * @return long the value of the receiver. - */ @Override public long longValue() { return value; } - /** - * Parses the string argument as if it was a short value and returns the - * result. Throws NumberFormatException if the string does not represent an - * short quantity. - * - * @param string - * a string representation of a short quantity. - * @return short the value represented by the argument - * @exception NumberFormatException - * if the argument could not be parsed as a short quantity. - */ + /** + * Parses the specified string as a signed decimal short value. The ASCII + * character \u002d ('-') is recognized as the minus sign. + * + * @param string + * the string representation of a short value. + * @return the primitive short value represented by {@code string}. + * @throws NumberFormatException + * if {@code string} is {@code null}, has a length of zero or + * can not be parsed as a short value. + */ public static short parseShort(String string) throws NumberFormatException { return parseShort(string, 10); } - /** - * Parses the string argument as if it was a short value and returns the - * result. Throws NumberFormatException if the string does not represent a - * single short quantity. The second argument specifies the radix to use - * when parsing the value. - * - * @param string - * a string representation of a short quantity. - * @param radix - * the radix to use when parsing. - * @return short the value represented by the argument - * @exception NumberFormatException - * if the argument could not be parsed as a short quantity. - */ + /** + * Parses the specified string as a signed short value using the specified + * radix. The ASCII character \u002d ('-') is recognized as the minus sign. + * + * @param string + * the string representation of a short value. + * @param radix + * the radix to use when parsing. + * @return the primitive short value represented by {@code string} using + * {@code radix}. + * @throws NumberFormatException + * if {@code string} is {@code null} or has a length of zero, + * {@code radix < Character.MIN_RADIX}, + * {@code radix > Character.MAX_RADIX}, or if {@code string} + * can not be parsed as a short value. + */ public static short parseShort(String string, int radix) throws NumberFormatException { int intValue = Integer.parseInt(string, radix); @@ -254,80 +213,77 @@ throw new NumberFormatException(); } - /** - * Answers the short value which the receiver represents - * - * @return short the value of the receiver. - */ - @Override + /** + * Gets the primitive value of this short. + * + * @return this object's primitive value. + */ + @Override public short shortValue() { return value; } - /** - * Answers a string containing a concise, human-readable description of the - * receiver. - * - * @return a printable representation for the receiver. - */ @Override public String toString() { return Integer.toString(value); } - /** - * Answers a string containing a concise, human-readable description of the - * argument. - * - * @param value - * short the short to convert. - * @return String a printable representation for the short. - */ + /** + * Returns a string containing a concise, human-readable description of the + * specified short value with radix 10. + * + * @param value + * the short to convert to a string. + * @return a printable representation of {@code value}. + */ public static String toString(short value) { return Integer.toString(value); } - /** - * Parses the string argument as if it was a short value and returns a Short - * representing the result. Throws NumberFormatException if the string does - * not represent a single short quantity. - * - * @param string - * a string representation of a short quantity. - * @return Short the value represented by the argument - * @exception NumberFormatException - * if the argument could not be parsed as a short quantity. - */ + /** + * Parses the specified string as a signed decimal short value. + * + * @param string + * the string representation of a short value. + * @return a {@code Short} instance containing the short value represented + * by {@code string}. + * @throws NumberFormatException + * if {@code string} is {@code null}, has a length of zero or + * can not be parsed as a short value. + * @see #parseShort(String) + */ public static Short valueOf(String string) throws NumberFormatException { return valueOf(parseShort(string)); } - /** - * Parses the string argument as if it was a short value and returns a Short - * representing the result. Throws NumberFormatException if the string does - * not represent a short quantity. The second argument specifies the radix - * to use when parsing the value. - * - * @param string - * a string representation of a short quantity. - * @param radix - * the radix to use when parsing. - * @return Short the value represented by the argument - * @exception NumberFormatException - * if the argument could not be parsed as a short quantity. - */ + /** + * Parses the specified string as a signed short value using the specified + * radix. + * + * @param string + * the string representation of a short value. + * @param radix + * the radix to use when parsing. + * @return a {@code Short} instance containing the short value represented + * by {@code string} using {@code radix}. + * @throws NumberFormatException + * if {@code string} is {@code null} or has a length of zero, + * {@code radix < Character.MIN_RADIX}, + * {@code radix > Character.MAX_RADIX}, or if {@code string} + * can not be parsed as a short value. + * @see #parseShort(String, int) + */ public static Short valueOf(String string, int radix) throws NumberFormatException { return valueOf(parseShort(string, radix)); } /** - *

- * Reverses the bytes of a short. - *

+ * Reverses the bytes of the specified short. * - * @param s The short to reverse. - * @return The reversed value. + * @param s + * the short value for which to reverse bytes. + * @return the reversed value. * @since 1.5 */ public static short reverseBytes(short s) { @@ -337,14 +293,15 @@ } /** + * Returns a {@code Short} instance for the specified short value. *

- * Returns a Short instance for the short - * value passed. This method is preferred over the constructor, as this - * method may maintain a cache of instances. - *

- * - * @param s The short value. - * @return A Short instance. + * If it is not necessary to get a new {@code Short} instance, it is + * recommended to use this method instead of the constructor, since it + * maintains a cache of instances which may result in better performance. + * + * @param s + * the short value to store in the instance. + * @return a {@code Short} instance containing {@code s}. * @since 1.5 */ public static Short valueOf(short s) { @@ -356,9 +313,7 @@ static class valueOfCache { /** - *

* A cache of instances used by {@link Short#valueOf(short)} and auto-boxing. - *

*/ private static final Short[] CACHE = new Short[256]; Modified: harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StackOverflowError.java URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StackOverflowError.java?rev=770909&r1=770908&r2=770909&view=diff ============================================================================== --- harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StackOverflowError.java (original) +++ harmony/enhanced/classlib/trunk/modules/luni/src/main/java/java/lang/StackOverflowError.java Sat May 2 08:09:50 2009 @@ -17,11 +17,10 @@ package java.lang; - /** - * This error is thrown when the depth of the callstack of the running program - * excedes some platform or virtual machine specific limit. Typically, this will - * occur only when a program becomes infinitely recursive, but can occur in + * Thrown when the depth of the callstack of the running program excedes some + * platform or virtual machine specific limit. Typically, this will occur only + * when a program becomes infinitely recursive, but it can also occur in * correctly written (but deeply recursive) programs. */ public class StackOverflowError extends java.lang.VirtualMachineError { @@ -29,20 +28,21 @@ private static final long serialVersionUID = 8609175038441759607L; /** - * Constructs a new instance of this class with its walkback filled in. - */ - public StackOverflowError() { - super(); - } + * Constructs a new {@code StackOverflowError} that includes the current + * stack trace. + */ + public StackOverflowError() { + super(); + } - /** - * Constructs a new instance of this class with its walkback and message - * filled in. - * - * @param detailMessage - * String The detail message for the exception. - */ - public StackOverflowError(String detailMessage) { - super(detailMessage); - } + /** + * Constructs a new {@code StackOverflowError} with the current stack trace + * and the specified detail message. + * + * @param detailMessage + * the detail message for this exception. + */ + public StackOverflowError(String detailMessage) { + super(detailMessage); + } }