harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
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 GMT
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);
+    }
     
     /**
-     * <p>Constructs a new instance with a message and cause.</p>
-     * @param message The message to assign to this exception.
-     * @param cause The optional cause of this exception; may be <code>null</code>.
+     * 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 @@
     }
     
     /**
-     * <p>Constructs a new instance with a cause.</p>
-     * @param cause The optional cause of this exception; may be <code>null</code>.
+     * 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.
+     * <p>
+     * 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 <code>name</code>. 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;
 
 /**
- * <p>
- * Short is the wrapper for the primitive type <code>short</code>.
- * </p>
+ * 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;
 
     /**
-     * <p>
-     * Constant for the maximum <code>short</code> value, 2<sup>15</sup>-1.
-     * </p>
+     * Constant for the maximum {@code short} value, 2<sup>15</sup>-1.
      */
     public static final short MAX_VALUE = (short) 0x7FFF;
 
     /**
-     * <p>
-     * Constant for the minimum <code>short</code> value, -2<sup>15</sup>.
-     * </p>
+     * Constant for the minimum {@code short} value, -2<sup>15</sup>.
      */
     public static final short MIN_VALUE = (short) 0x8000;
 
     /**
-     * <p>
-     * Constant for the number of bits to represent a <code>short</code> in
-     * two's compliment form.
-     * </p>
-     * 
+     * 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<Short> TYPE = (Class<Short>) 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;
 	}
 
     /**
-     * <p>
-     * Compares this <code>Short</code> to the <code>Short</code>
-     * 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.
-     * </p>
+     * Compares this object to the specified short object to determine their
+     * relative order.
      * 
-     * @param object The instance to compare to.
-     * @throws NullPointerException if <code>object</code> is
-     *         <code>null</code>.
+     * @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 <em>same</em> object using a class specific comparison.
-	 * <p>
-	 * 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 <code>true</code> if the object is the same as this object
-	 *         <code>false</code> 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 <code>true</code> when passed to <code>equals</code> 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));
 	}
     
     /**
-     * <p>
-     * Reverses the bytes of a <code>short</code>.
-     * </p>
+     * Reverses the bytes of the specified short.
      * 
-     * @param s The <code>short</code> 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.
      * <p>
-     * Returns a <code>Short</code> instance for the <code>short</code>
-     * value passed. This method is preferred over the constructor, as this
-     * method may maintain a cache of instances.
-     * </p>
-     * 
-     * @param s The short value.
-     * @return A <code>Short</code> 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 {
         /**
-         * <p>
          * A cache of instances used by {@link Short#valueOf(short)} and auto-boxing.
-         * </p>
          */
         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);
+    }
 }



Mime
View raw message