From: Michael Koch Date: Mon, 31 Mar 2003 10:15:48 +0000 (+0000) Subject: 2003-03-31 Michael Koch X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=da557ab84661f8906af7f8b55a8a4e68f4176258;p=platform%2Fupstream%2Fgcc.git 2003-03-31 Michael Koch * java/io/File.java (separator): Merged documentation from classpath. (separatorChar): Merged documentation from classpath. (pathSeparator): Merged documentation from classpath. (pathSeparatorChar): Merged documentation from classpath. (path): Merged documentation from classpath. (canRead): Merged documentation from classpath. (canWrite): Merged documentation from classpath. (createNewFile): Merged documentation from classpath. (delete): Merged documentation from classpath. (equals): Merged documentation from classpath. (exists): Merged documentation from classpath. (File): Renamed p to name to match classpath, merged documentation from classpath. (getAbsolutePath): Merged documentation from classpath. (getCanonicalPath): Merged documentation from classpath. (getCanonicalFile): Merged documentation from classpath. (getName): Merged documentation from classpath. (getParent): Merged documentation from classpath. (getParentFile): Merged documentation from classpath. (getPath): Merged documentation from classpath. (hashCode): Merged documentation from classpath. (isAbsolute): Merged documentation from classpath. (isDirectory): Merged documentation from classpath. (isFile): Merged documentation from classpath. (isHidden): Merged documentation from classpath. (lastModified): Merged documentation from classpath. (length): Merged documentation from classpath. (list): Merged documentation from classpath. (listFiles): Merged documentation from classpath. (toString): Merged documentation from classpath. (toURL): Merged documentation from classpath. (mkdir): Merged documentation from classpath. (mkdirs): Merged documentation from classpath. (createTempFile): Merged documentation from classpath. (setReadOnly): Merged documentation from classpath. (listRoots): Merged documentation from classpath. (compareTo): Merged documentation from classpath. (renameTo): Merged documentation from classpath. (setLastModified): Merged documentation from classpath. * java/io/PrintStream.java (auto_flush): Merged documentation from classpath. (PrintStream): Merged documentation from classpath. (checkError): Merged documentation from classpath. (setError): Merged documentation from classpath. (close): Merged documentation from classpath. (flush): Merged documentation from classpath. (print): Merged documentation from classpath. (println): Merged documentation from classpath. (write): Renamed count to len to match classpath, merged documentation from classpath. * java/io/RandomAccessFile.java (readShort): Merged documentation from classpath. (readUnsignedByte): Merged documentation from classpath. (readUnsignedShort): Merged documentation from classpath. (readUTF): Merged documentation from classpath. (seek): Reformatted, merged documentation from classpath. (skipBytes): Renamed some variables to match classpath, reformatted, merged documentation from classpath. (write): Merged documentation from classpath. (writeBoolean): Merged documentation from classpath. (writeByte): Merged documentation from classpath. (writeShort): Merged documentation from classpath. (writeChar): Merged documentation from classpath. (writeInt): Merged documentation from classpath. (writeLong): Merged documentation from classpath. (writeFloat): Merged documentation from classpath. (writeDouble): Merged documentation from classpath. (writeBytes): Merged documentation from classpath. (writeChars): Merged documentation from classpath. (writeUTF): Reformatted. (getChannel): Reformatted. From-SVN: r65081 --- diff --git a/libjava/ChangeLog b/libjava/ChangeLog index c685a6e..b131174 100644 --- a/libjava/ChangeLog +++ b/libjava/ChangeLog @@ -1,5 +1,80 @@ 2003-03-31 Michael Koch + * java/io/File.java + (separator): Merged documentation from classpath. + (separatorChar): Merged documentation from classpath. + (pathSeparator): Merged documentation from classpath. + (pathSeparatorChar): Merged documentation from classpath. + (path): Merged documentation from classpath. + (canRead): Merged documentation from classpath. + (canWrite): Merged documentation from classpath. + (createNewFile): Merged documentation from classpath. + (delete): Merged documentation from classpath. + (equals): Merged documentation from classpath. + (exists): Merged documentation from classpath. + (File): Renamed p to name to match classpath, merged documentation + from classpath. + (getAbsolutePath): Merged documentation from classpath. + (getCanonicalPath): Merged documentation from classpath. + (getCanonicalFile): Merged documentation from classpath. + (getName): Merged documentation from classpath. + (getParent): Merged documentation from classpath. + (getParentFile): Merged documentation from classpath. + (getPath): Merged documentation from classpath. + (hashCode): Merged documentation from classpath. + (isAbsolute): Merged documentation from classpath. + (isDirectory): Merged documentation from classpath. + (isFile): Merged documentation from classpath. + (isHidden): Merged documentation from classpath. + (lastModified): Merged documentation from classpath. + (length): Merged documentation from classpath. + (list): Merged documentation from classpath. + (listFiles): Merged documentation from classpath. + (toString): Merged documentation from classpath. + (toURL): Merged documentation from classpath. + (mkdir): Merged documentation from classpath. + (mkdirs): Merged documentation from classpath. + (createTempFile): Merged documentation from classpath. + (setReadOnly): Merged documentation from classpath. + (listRoots): Merged documentation from classpath. + (compareTo): Merged documentation from classpath. + (renameTo): Merged documentation from classpath. + (setLastModified): Merged documentation from classpath. + * java/io/PrintStream.java + (auto_flush): Merged documentation from classpath. + (PrintStream): Merged documentation from classpath. + (checkError): Merged documentation from classpath. + (setError): Merged documentation from classpath. + (close): Merged documentation from classpath. + (flush): Merged documentation from classpath. + (print): Merged documentation from classpath. + (println): Merged documentation from classpath. + (write): Renamed count to len to match classpath, + merged documentation from classpath. + * java/io/RandomAccessFile.java + (readShort): Merged documentation from classpath. + (readUnsignedByte): Merged documentation from classpath. + (readUnsignedShort): Merged documentation from classpath. + (readUTF): Merged documentation from classpath. + (seek): Reformatted, merged documentation from classpath. + (skipBytes): Renamed some variables to match classpath, reformatted, + merged documentation from classpath. + (write): Merged documentation from classpath. + (writeBoolean): Merged documentation from classpath. + (writeByte): Merged documentation from classpath. + (writeShort): Merged documentation from classpath. + (writeChar): Merged documentation from classpath. + (writeInt): Merged documentation from classpath. + (writeLong): Merged documentation from classpath. + (writeFloat): Merged documentation from classpath. + (writeDouble): Merged documentation from classpath. + (writeBytes): Merged documentation from classpath. + (writeChars): Merged documentation from classpath. + (writeUTF): Reformatted. + (getChannel): Reformatted. + +2003-03-31 Michael Koch + * java/awt/font/TextAttribute.java (readResolve): Throws java.io.InvalidObjectException. diff --git a/libjava/java/io/File.java b/libjava/java/io/File.java index 61dedff..83e4c2e 100644 --- a/libjava/java/io/File.java +++ b/libjava/java/io/File.java @@ -81,12 +81,94 @@ public class File implements Serializable, Comparable private final native boolean _access (int query); private final native boolean _stat (int query); + /** + * This is the path separator string for the current host. This field + * contains the value of the file.separator system property. + * An example separator string would be "/" on the GNU system. + */ + public static final String separator = System.getProperty("file.separator"); + + /** + * This is the first character of the file separator string. On many + * hosts (for example, on the GNU system), this represents the entire + * separator string. The complete separator string is obtained from the + * file.separatorsystem property. + */ + public static final char separatorChar = separator.charAt(0); + + /** + * This is the string that is used to separate the host name from the + * path name in paths than include the host name. It is the value of + * the path.separator system property. + */ + public static final String pathSeparator + = System.getProperty("path.separator"); + + /** + * This is the first character of the string used to separate the host name + * from the path name in paths that include a host. The separator string + * is taken from the path.separator system property. + */ + public static final char pathSeparatorChar = pathSeparator.charAt(0); + + + static final String tmpdir = System.getProperty("java.io.tmpdir"); + static int maxPathLen; + static boolean caseSensitive; + static String dupSeparator = separator + separator; + + static + { + init_native(); + } + + // Native function called at class initialization. This should should + // set the maxPathLen and caseSensitive variables. + private static native void init_native(); + + /** + * This is the path to the file set when the object is created. It + * may be an absolute or relative path name. + */ + private String path; + + // We keep a counter for use by createTempFile. We choose the first + // value randomly to try to avoid clashes with other VMs. + private static long counter = Double.doubleToLongBits (Math.random ()); + + /** + * This method tests whether or not the current thread is allowed to + * to read the file pointed to by this object. This will be true if and + * and only if 1) the file exists and 2) the SecurityManager + * (if any) allows access to the file via it's checkRead + * method 3) the file is readable. + * + * @return true if reading is allowed, + * false otherwise + * + * @exception SecurityException If the SecurityManager + * does not allow access to the file + */ public boolean canRead () { checkRead(); return _access (READ); } + /** + * This method test whether or not the current thread is allowed to + * write to this object. This will be true if and only if 1) The + * SecurityManager (if any) allows write access to the + * file and 2) The file exists and 3) The file is writable. To determine + * whether or not a non-existent file can be created, check the parent + * directory for write access. + * + * @return true if writing is allowed, false + * otherwise + * + * @exception SecurityException If the SecurityManager + * does not allow access to the file + */ public boolean canWrite () { checkWrite(); @@ -95,7 +177,23 @@ public class File implements Serializable, Comparable private native boolean performCreate() throws IOException; - /** @since 1.2 */ + /** + * This method creates a new file of zero length with the same name as + * the path of this File object if an only if that file + * does not already exist. + *

+ * A SecurityManagercheckWrite check is done prior + * to performing this action. + * + * @return true if the file was created, false if + * the file alread existed. + * + * @exception IOException If an I/O error occurs + * @exception SecurityException If the SecurityManager will + * not allow this operation to be performed. + * + * @since 1.2 + */ public boolean createNewFile() throws IOException { checkWrite(); @@ -103,6 +201,16 @@ public class File implements Serializable, Comparable } private native boolean performDelete (); + + /** + * This method deletes the file represented by this object. If this file + * is a directory, it must be empty in order for the delete to succeed. + * + * @return true if the file was deleted, false + * otherwise + * + * @exception SecurityException If deleting of the file is not allowed + */ public boolean delete () { SecurityManager s = System.getSecurityManager(); @@ -112,6 +220,21 @@ public class File implements Serializable, Comparable return performDelete (); } + /** + * This method tests two File objects for equality by + * comparing the path of the specified File against the path + * of this object. The two objects are equal if an only if 1) The + * argument is not null 2) The argument is a File object and + * 3) The path of the Fileargument is equal to the path + * of this object. + *

+ * The paths of the files are determined by calling the + * getPath() + * method on each object. + * + * @return true if the two objects are equal, + * false otherwise. + */ public boolean equals (Object obj) { if (! (obj instanceof File)) @@ -123,15 +246,29 @@ public class File implements Serializable, Comparable return (path.equalsIgnoreCase(other.path)); } + /** + * This method tests whether or not the file represented by the object + * actually exists on the filesystem. + * + * @return true if the file exists, falseotherwise. + * + * @exception SecurityException If reading of the file is not permitted + */ public boolean exists () { checkRead(); return _access (EXISTS); } - public File (String p) + /** + * This method initializes a new File object to represent + * a file with the specified path. + * + * @param name The path name of the file + */ + public File (String name) { - path = normalizePath(p); + path = normalizePath (name); } // Remove duplicate and redundant separator characters. @@ -195,7 +332,17 @@ public class File implements Serializable, Comparable return newpath.toString(); } - + + /** + * This method initializes a new File object to represent + * a file in the specified named directory. The path name to the file + * will be the directory name plus the separator string plus the file + * name. If the directory path name ends in the separator string, another + * separator string will still be appended. + * + * @param dirname The path to the directory the file resides in + * @param name The name of the file + */ public File (String dirPath, String name) { if (name == null) @@ -213,11 +360,30 @@ public class File implements Serializable, Comparable path = normalizePath(name); } - public File (File dir, String name) + /** + * This method initializes a new File object to represent + * a file in the specified directory. If the directory + * argument is null, the file is assumed to be in the + * current directory as specified by the user.dir system + * property + * + * @param directory The directory this file resides in + * @param name The name of the file + */ + public File (File directory, String name) { - this (dir == null ? null : dir.path, name); + this (directory == null ? null : directory.path, name); } + /** + * This method returns the path of this file as an absolute path name. + * If the path name is already absolute, then it is returned. Otherwise + * the value returned is the current directory plus the separatory + * string plus the path of the file. The current directory is determined + * from the user.dir system property. + * + * @return The absolute path of this file + */ public String getAbsolutePath () { if (isAbsolute ()) @@ -234,26 +400,70 @@ public class File implements Serializable, Comparable return System.getProperty ("user.dir") + separatorChar + path; } - /** @since 1.2 */ + /** + * This method returns a File object representing the + * absolute path of this object. + * + * @return A File with the absolute path of the object. + * + * @since 1.2 + */ public File getAbsoluteFile () { return new File (getAbsolutePath()); } + /** + * This method returns a canonical representation of the pathname of + * this file. The actual form of the canonical representation is + * different. On the GNU system, the canonical form differs from the + * absolute form in that all relative file references to "." and ".." + * are resolved and removed. + *

+ * Note that this method, unlike the other methods which return path + * names, can throw an IOException. This is because native method + * might be required in order to resolve the canonical path + * + * @exception IOException If an error occurs + */ public native String getCanonicalPath () throws IOException; - /** @since 1.2 */ + /** + * This method returns a File object representing the + * canonical path of this object. + * + * @return A File instance representing the canonical path of + * this object. + * + * @exception IOException If an error occurs. + * + * @since 1.2 + */ public File getCanonicalFile () throws IOException { return new File (getCanonicalPath()); } + /** + * This method returns the name of the file. This is everything in the + * complete path of the file after the last instance of the separator + * string. + * + * @return The file name + */ public String getName () { int last = path.lastIndexOf(separatorChar); return path.substring(last + 1); } + /** + * This method returns a String the represents this file's + * parent. null is returned if the file has no parent. The + * parent is determined via a simple operation which removes the + * + * @return The parent directory of this file + */ public String getParent () { int last = path.lastIndexOf(separatorChar); @@ -265,18 +475,40 @@ public class File implements Serializable, Comparable return path.substring(0, last); } - /** @since 1.2 */ + /** + * This method returns a File object representing the parent + * file of this one. + * + * @param A File for the parent of this object. + * null + * will be returned if this object does not have a parent. + * + * @since 1.2 + */ public File getParentFile () { String parent = getParent (); return (parent == null ? null : new File (parent)); } + /** + * Returns the path name that represents this file. May be a relative + * or an absolute path name + * + * @return The pathname of this file + */ public String getPath () { return path; } + /** + * This method returns a hash code representing this file. It is the + * hash code of the path of this file (as returned by getPath()) + * exclusived or-ed with the value 1234321. + * + * @return The hash code for this object + */ public int hashCode () { if (caseSensitive) @@ -285,33 +517,93 @@ public class File implements Serializable, Comparable return (path.toLowerCase().hashCode() ^ 1234321); } + /** + * This method returns true if this object represents an absolute file + * path and false if it does not. The definition of an absolute path varies + * by system. As an example, on GNU systems, a path is absolute if it starts + * with a "/". + * + * @return true if this object represents an absolute + * file name, false otherwise. + */ public native boolean isAbsolute (); + /** + * This method tests whether or not the file represented by this object + * is a directory. In order for this method to return true, + * the file represented by this object must exist and be a directory. + * + * @return true if this file is a directory, false + * otherwise + * + * @exception SecurityException If reading of the file is not permitted + */ public boolean isDirectory () { checkRead(); return _stat (DIRECTORY); } + /** + * This method tests whether or not the file represented by this object + * is a "plain" file. A file is a plain file if and only if it 1) Exists, + * 2) Is not a directory or other type of special file. + * + * @return true if this is a plain file, false + * otherwise + * + * @exception SecurityException If reading of the file is not permitted + */ public boolean isFile () { checkRead(); return _stat (ISFILE); } - /** @since 1.2 */ + /** + * This method tests whether or not this file represents a "hidden" file. + * On GNU systems, a file is hidden if its name begins with a "." + * character. Files with these names are traditionally not shown with + * directory listing tools. + * + * @return true if the file is hidden, false + * otherwise. + * + * @since 1.2 + */ public boolean isHidden() { checkRead(); return _stat (ISHIDDEN); } + /** + * This method returns the last modification time of this file. The + * time value returned is an abstract value that should not be interpreted + * as a specified time value. It is only useful for comparing to other + * such time values returned on the same system. In that case, the larger + * value indicates a more recent modification time. + *

+ * If the file does not exist, then a value of 0 is returned. + * + * @return The last modification time of the file + * + * @exception SecurityException If reading of the file is not permitted + */ public long lastModified () { checkRead(); return attr (MODIFIED); } + /** + * This method returns the length of the file represented by this object, + * or 0 if the specified file does not exist. + * + * @return The length of the file + * + * @exception SecurityException If reading of the file is not permitted + */ public long length () { checkRead(); @@ -322,44 +614,168 @@ public class File implements Serializable, Comparable FileFilter fileFilter, Class result_type); + /** + * This method returns a array of String's representing the + * list of files is then directory represented by this object. If this + * object represents a non-directory file or a non-existent file, then + * null is returned. The list of files will not contain + * any names such as "." or ".." which indicate the current or parent + * directory. Also, the names are not guaranteed to be sorted. + *

+ * In this form of the list() method, a filter is specified + * that allows the caller to control which files are returned in the + * list. The FilenameFilter specified is called for each + * file returned to determine whether or not that file should be included + * in the list. + *

+ * A SecurityManager check is made prior to reading the + * directory. If read access to the directory is denied, an exception + * will be thrown. + * + * @param filter An object which will identify files to exclude from + * the directory listing. + * + * @return An array of files in the directory, or null + * if this object does not represent a valid directory. + * + * @exception SecurityException If read access is not allowed to the + * directory by the SecurityManager + */ public String[] list (FilenameFilter filter) { checkRead(); return (String[]) performList (filter, null, String.class); } + /** + * This method returns a array of String's representing the + * list of files is then directory represented by this object. If this + * object represents a non-directory file or a non-existent file, then + * null is returned. The list of files will not contain + * any names such as "." or ".." which indicate the current or parent + * directory. Also, the names are not guaranteed to be sorted. + *

+ * A SecurityManager check is made prior to reading the + * directory. If read access to the directory is denied, an exception + * will be thrown. + * + * @return An array of files in the directory, or null if + * this object does not represent a valid directory. + * + * @exception SecurityException If read access is not allowed to the + * directory by the SecurityManager + */ public String[] list () { checkRead(); return (String[]) performList (null, null, String.class); } - /** @since 1.2 */ + /** + * This method returns an array of File objects representing + * all the files in the directory represented by this object. If this + * object does not represent a directory, null is returned. + * Each of the returned File object is constructed with this + * object as its parent. + *

+ * A SecurityManager check is made prior to reading the + * directory. If read access to the directory is denied, an exception + * will be thrown. + * + * @return An array of File objects for this directory. + * + * @exception SecurityException If the SecurityManager denies + * access to this directory. + * + * @since 1.2 + */ public File[] listFiles() { checkRead(); return (File[]) performList (null, null, File.class); } - /** @since 1.2 */ + /** + * This method returns an array of File objects representing + * all the files in the directory represented by this object. If this + * object does not represent a directory, null is returned. + * Each of the returned File object is constructed with this + * object as its parent. + *

+ * In this form of the listFiles() method, a filter is specified + * that allows the caller to control which files are returned in the + * list. The FilenameFilter specified is called for each + * file returned to determine whether or not that file should be included + * in the list. + *

+ * A SecurityManager check is made prior to reading the + * directory. If read access to the directory is denied, an exception + * will be thrown. + * + * @return An array of File objects for this directory. + * + * @exception SecurityException If the SecurityManager denies + * access to this directory. + * + * @since 1.2 + */ public File[] listFiles(FilenameFilter filter) { checkRead(); return (File[]) performList (filter, null, File.class); } - /** @since 1.2 */ + /** + * This method returns an array of File objects representing + * all the files in the directory represented by this object. If this + * object does not represent a directory, null is returned. + * Each of the returned File object is constructed with this + * object as its parent. + *

+ * In this form of the listFiles() method, a filter is specified + * that allows the caller to control which files are returned in the + * list. The FileFilter specified is called for each + * file returned to determine whether or not that file should be included + * in the list. + *

+ * A SecurityManager check is made prior to reading the + * directory. If read access to the directory is denied, an exception + * will be thrown. + * + * @return An array of File objects for this directory. + * + * @exception SecurityException If the SecurityManager denies + * access to this directory. + * + * @since 1.2 + */ public File[] listFiles(FileFilter filter) { checkRead(); return (File[]) performList (null, filter, File.class); } + /** + * This method returns a String that is the path name of the + * file as returned by getPath. + * + * @return A String representation of this file + */ public String toString () { return path; } + /** + * This method returns a URL with the file: + * protocol that represents this file. The exact form of this URL is + * system dependent. + * + * @return A URL for this object. + * + * @exception MalformedURLException If the URL cannot be created + * successfully. + */ public URL toURL () throws MalformedURLException { // On Win32, Sun's JDK returns URLs of the form "file:/c:/foo/bar.txt", @@ -374,6 +790,14 @@ public class File implements Serializable, Comparable private final native boolean performMkdir (); + /** + * This method creates a directory for the path represented by this object. + * + * @return true if the directory was created, + * false otherwise + * + * @exception SecurityException If write access is not allowed to this file + */ public boolean mkdir () { checkWrite(); @@ -396,6 +820,15 @@ public class File implements Serializable, Comparable return x.mkdir(); } + /** + * This method creates a directory for the path represented by this file. + * It will also create any intervening parent directories if necessary. + * + * @return true if the directory was created, + * false otherwise + * + * @exception SecurityException If write access is not allowed to this file + */ public boolean mkdirs () { checkWrite(); @@ -409,7 +842,36 @@ public class File implements Serializable, Comparable return Long.toString(counter++, Character.MAX_RADIX); } - /** @since 1.2 */ + /** + * This method creates a temporary file in the specified directory. If + * the directory name is null, then this method uses the system temporary + * directory. The files created are guaranteed not to currently exist and + * the same file name will never be used twice in the same virtual + * machine instance. + * The system temporary directory is determined by examinging the + * java.io.tmpdir system property. + *

+ * The prefix parameter is a sequence of at least three + * characters that are used as the start of the generated filename. The + * suffix parameter is a sequence of characters that is used + * to terminate the file name. This parameter may be null + * and if it is, the suffix defaults to ".tmp". + *

+ * If a SecurityManager exists, then its checkWrite + * method is used to verify that this operation is permitted. + * + * @param prefix The character prefix to use in generating the path name. + * @param suffix The character suffix to use in generating the path name. + * @param directory The directory to create the file in, or + * null for the default temporary directory + * + * @exception IllegalArgumentException If the patterns is not valid + * @exception SecurityException If there is no permission to perform + * this operation + * @exception IOException If an error occurs + * + * @since 1.2 + */ public static File createTempFile (String prefix, String suffix, File directory) throws IOException @@ -473,7 +935,20 @@ public class File implements Serializable, Comparable private native boolean performSetReadOnly(); - /** @since 1.2 */ + /** + * This method sets the file represented by this object to be read only. + * A read only file or directory cannot be modified. Please note that + * GNU systems allow read only files to be deleted if the directory it + * is contained in is writable. + * + * @return true if the operation succeeded, false + * otherwise. + * + * @exception SecurityException If the SecurityManager does + * not allow this operation. + * + * @since 1.2 + */ public boolean setReadOnly() { checkWrite(); @@ -482,7 +957,17 @@ public class File implements Serializable, Comparable private static native File[] performListRoots(); - /** @since 1.2 */ + /** + * This method returns an array of filesystem roots. Some operating systems + * have volume oriented filesystem. This method provides a mechanism for + * determining which volumes exist. GNU systems use a single hierarchical + * filesystem, so will have only one "/" filesystem root. + * + * @return An array of File objects for each filesystem root + * available. + * + * @since 1.2 + */ public static File[] listRoots() { File[] roots = performListRoots(); @@ -519,13 +1004,55 @@ public class File implements Serializable, Comparable return roots; } + /** + * This method creates a temporary file in the system temporary directory. + * The files created are guaranteed not to currently exist and the same file + * name will never be used twice in the same virtual machine instance. The + * system temporary directory is determined by examinging the + * java.io.tmpdir system property. + *

+ * The prefix parameter is a sequence of at least three + * characters that are used as the start of the generated filename. The + * suffix parameter is a sequence of characters that is used + * to terminate the file name. This parameter may be null + * and if it is, the suffix defaults to ".tmp". + *

+ * If a SecurityManager exists, then its checkWrite + * method is used to verify that this operation is permitted. + *

+ * This method is identical to calling + * createTempFile(prefix, suffix, null). + * + * @param prefix The character prefix to use in generating the path name. + * @param suffix The character suffix to use in generating the path name. + * + * @exception IllegalArgumentException If the prefix or suffix are not valid. + * @exception SecurityException If there is no permission to perform + * this operation + * @exception IOException If an error occurs + */ public static File createTempFile (String prefix, String suffix) throws IOException { return createTempFile (prefix, suffix, null); } - /** @since 1.2 */ + /** + * This method compares the specified File to this one + * to test for equality. It does this by comparing the canonical path names + * of the files. + *

+ * The canonical paths of the files are determined by calling the + * getCanonicalPath method on each object. + *

+ * This method returns a 0 if the specified Object is equal + * to this one, a negative value if it is less than this one + * a positive value if it is greater than this one. + * + * @return An integer as described above + * + * @since 1.2 + */ public int compareTo(File other) { if (caseSensitive) @@ -534,7 +1061,27 @@ public class File implements Serializable, Comparable return path.compareToIgnoreCase (other.path); } - /** @since 1.2 */ + /** + * This method compares the specified Object to this one + * to test for equality. It does this by comparing the canonical path names + * of the files. This method is identical to compareTo(File) + * except that if the Object passed to it is not a + * File, it throws a ClassCastException + *

+ * The canonical paths of the files are determined by calling the + * getCanonicalPath method on each object. + *

+ * This method returns a 0 if the specified Object is equal + * to this one, a negative value if it is less than this one + * a positive value if it is greater than this one. + * + * @return An integer as described above + * + * @exception ClassCastException If the passed Object is + * not a File + * + * @since 1.2 + */ public int compareTo(Object o) { File other = (File) o; @@ -542,6 +1089,19 @@ public class File implements Serializable, Comparable } private native boolean performRenameTo (File dest); + + /** + * This method renames the file represented by this object to the path + * of the file represented by the argument File. + * + * @param dest The File object representing the target name + * + * @return true if the rename succeeds, false + * otherwise. + * + * @exception SecurityException If write access is not allowed to the + * file by the SecurityMananger. + */ public boolean renameTo (File dest) { SecurityManager s = System.getSecurityManager(); @@ -556,41 +1116,29 @@ public class File implements Serializable, Comparable } private native boolean performSetLastModified(long time); - - /** @since 1.2 */ + + /** + * This method sets the modification time on the file to the specified + * value. This is specified as the number of seconds since midnight + * on January 1, 1970 GMT. + * + * @param time The desired modification time. + * + * @return true if the operation succeeded, false + * otherwise. + * + * @exception IllegalArgumentException If the specified time is negative. + * @exception SecurityException If the SecurityManager will + * not allow this operation. + * + * @since 1.2 + */ public boolean setLastModified(long time) { checkWrite(); return performSetLastModified(time); } - public static final String pathSeparator - = System.getProperty("path.separator"); - public static final char pathSeparatorChar = pathSeparator.charAt(0); - public static final String separator = System.getProperty("file.separator"); - public static final char separatorChar = separator.charAt(0); - - static final String tmpdir = System.getProperty("java.io.tmpdir"); - static int maxPathLen; - static boolean caseSensitive; - static String dupSeparator = separator + separator; - - static - { - init_native(); - } - - // Native function called at class initialization. This should should - // set the maxPathLen and caseSensitive variables. - private static native void init_native(); - - // The path. - private String path; - - // We keep a counter for use by createTempFile. We choose the first - // value randomly to try to avoid clashes with other VMs. - private static long counter = Double.doubleToLongBits (Math.random ()); - private void checkWrite () { SecurityManager s = System.getSecurityManager(); diff --git a/libjava/java/io/PrintStream.java b/libjava/java/io/PrintStream.java index 9563305..418d7f2 100644 --- a/libjava/java/io/PrintStream.java +++ b/libjava/java/io/PrintStream.java @@ -84,32 +84,76 @@ public class PrintStream extends FilterOutputStream // True if error occurred. private boolean error; // True if auto-flush. + /** + * This is true if auto-flush is enabled, + * false otherwise + */ private boolean auto_flush; + /** + * This method intializes a new PrintStream object to write + * to the specified output sink. Note that this class is deprecated in + * favor of PrintWriter. + * + * @param out The OutputStream to write to. + * + * @deprecated + */ public PrintStream (OutputStream out) { this(out, false); } + /** + * This method intializes a new PrintStream object to write + * to the specified output sink. This constructor also allows "auto-flush" + * functionality to be specified where the stream will be flushed after + * every line is terminated or newline character is written. + *

+ * Note that this class is deprecated in favor of PrintWriter. + * + * @param out The OutputStream to write to. + * @param auto_flush true to flush the stream after every + * line, false otherwise + * + * @deprecated + */ public PrintStream (OutputStream out, boolean auto_flush) { super(out); + converter = UnicodeToBytes.getDefaultEncoder(); error = false; this.auto_flush = auto_flush; } + /** + * This method checks to see if an error has occurred on this stream. Note + * that once an error has occurred, this method will continue to report + * true forever for this stream. Before checking for an + * error condition, this method flushes the stream. + * + * @return true if an error has occurred, + * false otherwise + */ public boolean checkError () { flush(); return error; } + /** + * This method can be called by subclasses to indicate that an error + * has occurred and should be reported by checkError. + */ protected void setError () { error = true; } + /** + * This method closes this stream and all underlying streams. + */ public void close () { try @@ -127,6 +171,10 @@ public class PrintStream extends FilterOutputStream } } + /** + * This method flushes any buffered bytes to the underlying stream and + * then flushes that stream as well. + */ public void flush () { try @@ -210,103 +258,245 @@ public class PrintStream extends FilterOutputStream } } + /** + * This methods prints a boolean value to the stream. true + * values are printed as "true" and false values are printed + * as "false". + * + * @param b The boolean value to print + */ public void print (boolean bool) { print(String.valueOf(bool), false); } + /** + * This method prints an integer to the stream. The value printed is + * determined using the String.valueOf() method. + * + * @param inum The int value to be printed + */ public void print (int inum) { print(String.valueOf(inum), false); } + /** + * This method prints a long to the stream. The value printed is + * determined using the String.valueOf() method. + * + * @param lnum The long value to be printed + */ public void print (long lnum) { print(String.valueOf(lnum), false); } + /** + * This method prints a float to the stream. The value printed is + * determined using the String.valueOf() method. + * + * @param fnum The float value to be printed + */ public void print (float fnum) { print(String.valueOf(fnum), false); } + /** + * This method prints a double to the stream. The value printed is + * determined using the String.valueOf() method. + * + * @param dnum The double value to be printed + */ public void print (double dnum) { print(String.valueOf(dnum), false); } + /** + * This method prints an Object to the stream. The actual + * value printed is determined by calling the String.valueOf() + * method. + * + * @param obj The Object to print. + */ public void print (Object obj) { print(obj == null ? "null" : obj.toString(), false); } + /** + * This method prints a String to the stream. The actual + * value printed depends on the system default encoding. + * + * @param str The String to print. + */ public void print (String str) { print(str == null ? "null" : str, false); } + /** + * This method prints a char to the stream. The actual value printed is + * determined by the character encoding in use. + * + * @param ch The char value to be printed + */ public synchronized void print (char ch) { work[0] = ch; print(work, 0, 1, false); } + /** + * This method prints an array of characters to the stream. The actual + * value printed depends on the system default encoding. + * + * @param s The array of characters to print. + */ public void print (char[] charArray) { print(charArray, 0, charArray.length, false); } + /** + * This method prints a line separator sequence to the stream. The value + * printed is determined by the system property

line.separator + * and is not necessarily the Unix '\n' newline character. + */ public void println () { print(line_separator, 0, line_separator.length, false); } + /** + * This methods prints a boolean value to the stream. true + * values are printed as "true" and false values are printed + * as "false". + *

+ * This method prints a line termination sequence after printing the value. + * + * @param b The boolean value to print + */ public void println (boolean bool) { print(String.valueOf(bool), true); } + /** + * This method prints an integer to the stream. The value printed is + * determined using the String.valueOf() method. + *

+ * This method prints a line termination sequence after printing the value. + * + * @param inum The int value to be printed + */ public void println (int inum) { print(String.valueOf(inum), true); } + /** + * This method prints a long to the stream. The value printed is + * determined using the String.valueOf() method. + *

+ * This method prints a line termination sequence after printing the value. + * + * @param lnum The long value to be printed + */ public void println (long lnum) { print(String.valueOf(lnum), true); } + /** + * This method prints a float to the stream. The value printed is + * determined using the String.valueOf() method. + *

+ * This method prints a line termination sequence after printing the value. + * + * @param fnum The float value to be printed + */ public void println (float fnum) { print(String.valueOf(fnum), true); } + /** + * This method prints a double to the stream. The value printed is + * determined using the String.valueOf() method. + *

+ * This method prints a line termination sequence after printing the value. + * + * @param dnum The double value to be printed + */ public void println (double dnum) { print(String.valueOf(dnum), true); } + /** + * This method prints an Object to the stream. The actual + * value printed is determined by calling the String.valueOf() + * method. + *

+ * This method prints a line termination sequence after printing the value. + * + * @param obj The Object to print. + */ public void println (Object obj) { print(obj == null ? "null" : obj.toString(), true); } + /** + * This method prints a String to the stream. The actual + * value printed depends on the system default encoding. + *

+ * This method prints a line termination sequence after printing the value. + * + * @param str The String to print. + */ public void println (String str) { print (str == null ? "null" : str, true); } + /** + * This method prints a char to the stream. The actual value printed is + * determined by the character encoding in use. + *

+ * This method prints a line termination sequence after printing the value. + * + * @param ch The char value to be printed + */ public synchronized void println (char ch) { work[0] = ch; print(work, 0, 1, true); } + /** + * This method prints an array of characters to the stream. The actual + * value printed depends on the system default encoding. + *

+ * This method prints a line termination sequence after printing the value. + * + * @param s The array of characters to print. + */ public void println (char[] charArray) { print(charArray, 0, charArray.length, true); } + /** + * This method writes a byte of data to the stream. If auto-flush is + * enabled, printing a newline character will cause the stream to be + * flushed after the character is written. + * + * @param b The byte to be written + */ public void write (int oneByte) { try @@ -325,11 +515,20 @@ public class PrintStream extends FilterOutputStream } } - public void write (byte[] buffer, int offset, int count) + /** + * This method writes len bytes from the specified array + * starting at index offset into the array. + * + * @param buffer The array of bytes to write + * @param offset The index into the array to start writing from + * @param len The number of bytes to write + */ + public void write (byte[] buffer, int offset, int len) { try { - out.write(buffer, offset, count); + out.write (buffer, offset, len); + if (auto_flush) flush(); } @@ -343,4 +542,5 @@ public class PrintStream extends FilterOutputStream } } -} +} // class PrintStream + diff --git a/libjava/java/io/RandomAccessFile.java b/libjava/java/io/RandomAccessFile.java index afe54a6..990b2dc 100644 --- a/libjava/java/io/RandomAccessFile.java +++ b/libjava/java/io/RandomAccessFile.java @@ -525,100 +525,391 @@ public class RandomAccessFile implements DataOutput, DataInput return in.readLong(); } + /** + * This method reads a signed 16-bit value into a Java in from the stream. + * It operates by reading two bytes from the stream and converting them to + * a single 16-bit Java short The two bytes are stored most + * significant byte first (i.e., "big endian") regardless of the native + * host byte ordering. + *

+ * As an example, if byte1 and code{byte2 + * represent the first + * and second byte read from the stream respectively, they will be + * transformed to a short in the following manner: + *

+ * (short)(((byte1 & 0xFF) << 8) | (byte2 & 0xFF) + *

+ * The value returned is in the range of -32768 to 32767. + *

+ * This method can read a short written by an object + * implementing the + * writeShort() method in the DataOutput interface. + * + * @return The short value read + * + * @exception EOFException If end of file is reached before reading the value + * @exception IOException If any other error occurs + * + * @see DataOutput + */ public final short readShort () throws IOException { return in.readShort(); } + /** + * This method reads 8 unsigned bits into a Java int value + * from the + * stream. The value returned is in the range of 0 to 255. + *

+ * This method can read an unsigned byte written by an object implementing + * the writeUnsignedByte() method in the + * DataOutput interface. + * + * @return The unsigned bytes value read as a Java int + * + * @exception EOFException If end of file is reached before reading the value + * @exception IOException If any other error occurs + * + * @see DataOutput + */ public final int readUnsignedByte () throws IOException { return in.readUnsignedByte(); } + /** + * This method reads 16 unsigned bits into a Java int value from the stream. + * It operates by reading two bytes from the stream and converting them to + * a single Java int The two bytes are stored most + * significant byte first (i.e., "big endian") regardless of the native + * host byte ordering. + *

+ * As an example, if byte1 and byte2 + * represent the first + * and second byte read from the stream respectively, they will be + * transformed to an int in the following manner: + *

+ * (int)(((byte1 & 0xFF) << 8) + (byte2 & 0xFF)) + *

+ * The value returned is in the range of 0 to 65535. + *

+ * This method can read an unsigned short written by an object implementing + * the writeUnsignedShort() method in the + * DataOutput interface. + * + * @return The unsigned short value read as a Java int + * + * @exception EOFException If end of file is reached before reading the value + * @exception IOException If any other error occurs + */ public final int readUnsignedShort () throws IOException { return in.readUnsignedShort(); } + /** + * This method reads a String from an input stream that + * is encoded in + * a modified UTF-8 format. This format has a leading two byte sequence + * that contains the remaining number of bytes to read. This two byte + * sequence is read using the readUnsignedShort() method of this + * interface. + *

+ * After the number of remaining bytes have been determined, these bytes + * are read an transformed into char values. + * These char values + * are encoded in the stream using either a one, two, or three byte format. + * The particular format in use can be determined by examining the first + * byte read. + *

+ * If the first byte has a high order bit of 0 then + * that character consists on only one byte. This character value consists + * of seven bits that are at positions 0 through 6 of the byte. As an + * example, if byte1 is the byte read from the stream, it would + * be converted to a char like so: + *

+ * (char)byte1 + *

+ * If the first byte has 110 as its high order bits, then the + * character consists of two bytes. The bits that make up the character + * value are in positions 0 through 4 of the first byte and bit positions + * 0 through 5 of the second byte. (The second byte should have + * 10 as its high order bits). These values are in most significant + * byte first (i.e., "big endian") order. + *

+ * As an example, if byte1 and byte2 + * are the first two bytes + * read respectively, and the high order bits of them match the patterns + * which indicate a two byte character encoding, then they would be + * converted to a Java char like so: + *

+ * (char)(((byte1 & 0x1F) << 6) | (byte2 & 0x3F)) + *

+ * If the first byte has a 1110 as its high order bits, then the + * character consists of three bytes. The bits that make up the character + * value are in positions 0 through 3 of the first byte and bit positions + * 0 through 5 of the other two bytes. (The second and third bytes should + * have 10 as their high order bits). These values are in most + * significant byte first (i.e., "big endian") order. + *

+ * As an example, if byte1 byte2 + * and byte3 are the + * three bytes read, and the high order bits of them match the patterns + * which indicate a three byte character encoding, then they would be + * converted to a Java char like so: + *

+ * (char)(((byte1 & 0x0F) << 12) | ((byte2 & 0x3F) << 6) | + * (byte3 & 0x3F)) + *

+ * Note that all characters are encoded in the method that requires the + * fewest number of bytes with the exception of the character with the + * value of \u0000 which is encoded as two bytes. This is + * a modification of the UTF standard used to prevent C language style + * NUL values from appearing in the byte stream. + *

+ * This method can read data that was written by an object implementing the + * writeUTF() method in DataOutput + * + * @return The String read + * + * @exception EOFException If end of file is reached before reading the + * String + * @exception UTFDataFormatException If the data is not in UTF-8 format + * @exception IOException If any other error occurs + * + * @see DataOutput + */ public final String readUTF () throws IOException { return in.readUTF(); } + /** + * This method sets the current file position to the specified offset + * from the beginning of the file. Note that some operating systems will + * allow the file pointer to be set past the current end of the file. + * + * @param pos The offset from the beginning of the file at which to set + * the file pointer + * + * @exception IOException If an error occurs + */ public void seek (long pos) throws IOException { - fd.seek(pos, FileDescriptor.SET, false); + fd.seek (pos, FileDescriptor.SET, false); } - public int skipBytes (int count) throws IOException + /** + * This method attempts to skip and discard the specified number of bytes + * in the input stream. It may actually skip fewer bytes than requested. + * The actual number of bytes skipped is returned. This method will not + * skip any bytes if passed a negative number of bytes to skip. + * + * @param numBytes The requested number of bytes to skip. + * + * @return The number of bytes actually skipped. + * + * @exception IOException If an error occurs. + */ + public int skipBytes (int numBytes) throws IOException { - if (count <= 0) + if (numBytes < 0) + throw new IllegalArgumentException ("Can't skip negative bytes: " + + numBytes); + + if (numBytes == 0) return 0; - long startPos = fd.getFilePointer(); - long endPos = fd.seek(count, FileDescriptor.CUR, true); - return (int) (endPos - startPos); + + long curPos = fd.getFilePointer (); + long newPos = fd.seek (numBytes, FileDescriptor.CUR, true); + + return (int) (newPos - curPos); } + /** + * This method writes a single byte of data to the file. The file must + * be open for read-write in order for this operation to succeed. + * + * @param The byte of data to write, passed as an int. + * + * @exception IOException If an error occurs + */ public void write (int oneByte) throws IOException { out.write(oneByte); } + /** + * This method writes all the bytes in the specified array to the file. + * The file must be open read-write in order for this operation to succeed. + * + * @param buf The array of bytes to write to the file + */ public void write (byte[] buffer) throws IOException { out.write(buffer); } - public void write (byte[] buffer, int offset, int count) throws IOException + /** + * This method writes len bytes to the file from the specified + * array starting at index offset into the array. + * + * @param buf The array of bytes to write to the file + * @param offset The index into the array to start writing file + * @param len The number of bytes to write + * + * @exception IOException If an error occurs + */ + public void write (byte[] buffer, int offset, int len) throws IOException { - out.write(buffer, offset, count); + out.write (buffer, offset, len); } + /** + * This method writes a Java boolean to the underlying output + * stream. For a value of true, 1 is written to the stream. + * For a value of false, 0 is written. + * + * @param b The boolean value to write to the stream + * + * @exception IOException If an error occurs + */ public final void writeBoolean (boolean val) throws IOException { out.writeBoolean(val); } + /** + * This method writes a Java byte value to the underlying + * output stream. + * + * @param b The byte to write to the stream, passed + * as an int. + * + * @exception IOException If an error occurs + */ public final void writeByte (int v) throws IOException { out.writeByte(v); } + /** + * This method writes a Java short to the stream, high byte + * first. This method requires two bytes to encode the value. + * + * @param s The short value to write to the stream, + * passed as an int. + * + * @exception IOException If an error occurs + */ public final void writeShort (int v) throws IOException { out.writeShort(v); } + /** + * This method writes a single char value to the stream, + * high byte first. + * + * @param v The char value to write, passed as + * an int. + * + * @exception IOException If an error occurs + */ public final void writeChar (int v) throws IOException { out.writeChar(v); } + /** + * This method writes a Java int to the stream, high bytes + * first. This method requires four bytes to encode the value. + * + * @param v The int value to write to the stream. + * + * @exception IOException If an error occurs + */ public final void writeInt (int v) throws IOException { out.writeInt(v); } + /** + * This method writes a Java long to the stream, high bytes + * first. This method requires eight bytes to encode the value. + * + * @param v The long value to write to the stream. + * + * @exception IOException If an error occurs + */ public final void writeLong (long v) throws IOException { out.writeLong(v); } + /** + * This method writes a Java float value to the stream. This + * value is written by first calling the method + * Float.floatToIntBits + * to retrieve an int representing the floating point number, + * then writing this int value to the stream exactly the same + * as the writeInt() method does. + * + * @param v The floating point number to write to the stream. + * + * @exception IOException If an error occurs + * + * @see #writeInt(int) + */ public final void writeFloat (float v) throws IOException { out.writeFloat(v); } + /** + * This method writes a Java double value to the stream. This + * value is written by first calling the method + * Double.doubleToLongBits + * to retrieve an long representing the floating point number, + * then writing this long value to the stream exactly the same + * as the writeLong() method does. + * + * @param v The double precision floating point number to write to the + * stream. + * + * @exception IOException If an error occurs + * + * @see #writeLong(long) + */ public final void writeDouble (double v) throws IOException { out.writeDouble(v); } + /** + * This method writes all the bytes in a String out to the + * stream. One byte is written for each character in the String. + * The high eight bits of each character are discarded. + * + * @param s The String to write to the stream + * + * @exception IOException If an error occurs + */ public final void writeBytes (String s) throws IOException { out.writeBytes(s); } - + + /** + * This method writes all the characters in a String to the + * stream. There will be two bytes for each character value. The high + * byte of the character will be written first. + * + * @param s The String to write to the stream. + * + * @exception IOException If an error occurs + */ public final void writeChars (String s) throws IOException { out.writeChars(s); @@ -653,7 +944,7 @@ public class RandomAccessFile implements DataOutput, DataInput * * @exception IOException If an error occurs */ - public final void writeUTF(String s) throws IOException + public final void writeUTF (String s) throws IOException { out.writeUTF(s); } @@ -664,7 +955,7 @@ public class RandomAccessFile implements DataOutput, DataInput * A file channel must be created by first creating an instance of * Input/Output/RandomAccessFile and invoking the getChannel() method on it. */ - public synchronized FileChannel getChannel() + public synchronized FileChannel getChannel () { if (ch == null) ch = new FileChannelImpl (fd, true, this);