1 /* File.java -- Class representing a file on disk
2 Copyright (C) 1998, 1999, 2000, 2001, 2003, 2004, 2005, 2006, 2007
3 Free Software Foundation, Inc.
5 This file is part of GNU Classpath.
7 GNU Classpath is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2, or (at your option)
12 GNU Classpath is distributed in the hope that it will be useful, but
13 WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with GNU Classpath; see the file COPYING. If not, write to the
19 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
22 Linking this library statically or dynamically with other modules is
23 making a combined work based on this library. Thus, the terms and
24 conditions of the GNU General Public License cover the whole
27 As a special exception, the copyright holders of this library give you
28 permission to link this library with independent modules to produce an
29 executable, regardless of the license terms of these independent
30 modules, and to copy and distribute the resulting executable under
31 terms of your choice, provided that you also meet, for each linked
32 independent module, the terms and conditions of the license of that
33 module. An independent module is a module which is not derived from
34 or based on this library. If you modify this library, you may extend
35 this exception to your version of the library, but you are not
36 obligated to do so. If you do not wish to do so, delete this
37 exception statement from your version. */
42 import java
.net
.MalformedURLException
;
44 import java
.net
.URISyntaxException
;
46 import gnu
.classpath
.Configuration
;
48 /* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
49 * "The Java Language Specification", ISBN 0-201-63451-1
50 * Status: Complete to version 1.3.
54 * This class represents a file or directory on a local disk. It provides
55 * facilities for dealing with a variety of systems that use various
56 * types of path separators ("/" versus "\", for example). It also
57 * contains method useful for creating and deleting files and directories.
59 * @author Aaron M. Renn (arenn@urbanophile.com)
60 * @author Tom Tromey (tromey@cygnus.com)
62 public class File
implements Serializable
, Comparable
<File
>
64 private static final long serialVersionUID
= 301077366599181567L;
66 // QUERY arguments to access function.
67 private final static int READ
= 0;
68 private final static int WRITE
= 1;
69 private final static int EXISTS
= 2;
70 private final static int EXEC
= 3;
72 // QUERY arguments to stat function.
73 private final static int DIRECTORY
= 0;
74 private final static int ISFILE
= 1;
75 private final static int ISHIDDEN
= 2;
77 // QUERY arguments to attr function.
78 private final static int MODIFIED
= 0;
79 private final static int LENGTH
= 1;
81 private final native long attr (int query
);
82 // On OSF1 V5.0, `stat' is a macro. It is easiest to use the name
83 // `_stat' instead. We do the same thing for `_access' just in
85 private final native boolean _access (int query
);
86 private final native boolean _stat (int query
);
89 * This is the path separator string for the current host. This field
90 * contains the value of the <code>file.separator</code> system property.
91 * An example separator string would be "/" on the GNU system.
93 public static final String separator
= System
.getProperty("file.separator");
94 private static final String dupSeparator
= separator
+ separator
;
97 * This is the first character of the file separator string. On many
98 * hosts (for example, on the GNU system), this represents the entire
99 * separator string. The complete separator string is obtained from the
100 * <code>file.separator</code>system property.
102 public static final char separatorChar
= separator
.charAt(0);
105 * This is the string that is used to separate the host name from the
106 * path name in paths that include the host name. It is the value of
107 * the <code>path.separator</code> system property.
109 public static final String pathSeparator
110 = System
.getProperty("path.separator");
113 * This is the first character of the string used to separate the host name
114 * from the path name in paths that include a host. The separator string
115 * is taken from the <code>path.separator</code> system property.
117 public static final char pathSeparatorChar
= pathSeparator
.charAt(0);
119 static final String tmpdir
= System
.getProperty("java.io.tmpdir");
120 /* If 0, then the system doesn't have a file name length limit. */
121 static int maxPathLen
;
122 static boolean caseSensitive
;
126 if (Configuration
.INIT_LOAD_LIBRARY
)
128 System
.loadLibrary("javaio");
134 // Native function called at class initialization. This should should
135 // set the maxPathLen and caseSensitive variables.
136 private static native void init_native();
139 * This is the path to the file set when the object is created. It
140 * may be an absolute or relative path name.
144 // We keep a counter for use by createTempFile. We choose the first
145 // value randomly to try to avoid clashes with other VMs.
146 private static long counter
= Double
.doubleToLongBits (Math
.random());
149 * This method tests whether or not the current thread is allowed to
150 * to read the file pointed to by this object. This will be true if and
151 * and only if 1) the file exists and 2) the <code>SecurityManager</code>
152 * (if any) allows access to the file via it's <code>checkRead</code>
153 * method 3) the file is readable.
155 * @return <code>true</code> if reading is allowed,
156 * <code>false</code> otherwise
158 * @exception SecurityException If the <code>SecurityManager</code>
159 * does not allow access to the file
161 public boolean canRead()
164 return _access (READ
);
168 * This method test whether or not the current thread is allowed to
169 * write to this object. This will be true if and only if 1) The
170 * <code>SecurityManager</code> (if any) allows write access to the
171 * file and 2) The file exists and 3) The file is writable. To determine
172 * whether or not a non-existent file can be created, check the parent
173 * directory for write access.
175 * @return <code>true</code> if writing is allowed, <code>false</code>
178 * @exception SecurityException If the <code>SecurityManager</code>
179 * does not allow access to the file
181 public boolean canWrite()
184 return _access (WRITE
);
188 * This method tests whether or not the current thread is allowed to
189 * to execute the file pointed to by this object. This will be true if and
190 * and only if 1) the file exists and 2) the <code>SecurityManager</code>
191 * (if any) allows access to the file via it's <code>checkExec</code>
192 * method 3) the file is executable.
194 * @return <code>true</code> if execution is allowed,
195 * <code>false</code> otherwise
197 * @exception SecurityException If the <code>SecurityManager</code>
198 * does not allow access to the file
200 public boolean canExecute()
205 return _access (EXEC
);
208 private native boolean performCreate() throws IOException
;
211 * This method creates a new file of zero length with the same name as
212 * the path of this <code>File</code> object if an only if that file
213 * does not already exist.
215 * A <code>SecurityManager.checkWrite</code> check is done prior
216 * to performing this action.
218 * @return <code>true</code> if the file was created, <code>false</code> if
219 * the file alread existed.
221 * @exception IOException If an I/O error occurs
222 * @exception SecurityException If the <code>SecurityManager</code> will
223 * not allow this operation to be performed.
227 public boolean createNewFile() throws IOException
230 return performCreate();
234 * This native method handles the actual deleting of the file
236 private native boolean performDelete();
239 * This method deletes the file represented by this object. If this file
240 * is a directory, it must be empty in order for the delete to succeed.
242 * @return <code>true</code> if the file was deleted, <code>false</code>
245 * @exception SecurityException If deleting of the file is not allowed
247 public synchronized boolean delete()
249 SecurityManager s
= System
.getSecurityManager();
254 return performDelete();
258 * This method tests two <code>File</code> objects for equality by
259 * comparing the path of the specified <code>File</code> against the path
260 * of this object. The two objects are equal if an only if 1) The
261 * argument is not null 2) The argument is a <code>File</code> object and
262 * 3) The path of the <code>File</code>argument is equal to the path
265 * The paths of the files are determined by calling the
266 * <code>getPath()</code>
267 * method on each object.
269 * @return <code>true</code> if the two objects are equal,
270 * <code>false</code> otherwise.
272 public boolean equals(Object obj
)
274 if (! (obj
instanceof File
))
277 File other
= (File
) obj
;
280 return path
.equals(other
.path
);
282 return path
.equalsIgnoreCase(other
.path
);
286 * This method tests whether or not the file represented by the
287 * object actually exists on the filesystem.
289 private boolean internalExists()
291 return _access (EXISTS
);
295 * This method tests whether or not the file represented by the object
296 * actually exists on the filesystem.
298 * @return <code>true</code> if the file exists, <code>false</code>otherwise.
300 * @exception SecurityException If reading of the file is not permitted
302 public boolean exists()
305 return internalExists();
309 * This method initializes a new <code>File</code> object to represent
310 * a file with the specified path.
312 * @param name The path name of the file
314 public File(String name
)
316 path
= normalizePath (name
);
319 // Remove duplicate and redundant separator characters.
320 private String
normalizePath(String p
)
322 // On Windows, convert any '/' to '\'. This appears to be the same logic
323 // that Sun's Win32 Java performs.
324 if (separatorChar
== '\\')
326 p
= p
.replace ('/', '\\');
327 // We have to special case the "\c:" prefix.
328 if (p
.length() > 2 && p
.charAt(0) == '\\' &&
329 ((p
.charAt(1) >= 'a' && p
.charAt(1) <= 'z') ||
330 (p
.charAt(1) >= 'A' && p
.charAt(1) <= 'Z')) &&
335 int dupIndex
= p
.indexOf(dupSeparator
);
336 int plen
= p
.length();
338 // Special case: permit Windows UNC path prefix.
339 if (dupSeparator
.equals("\\\\") && dupIndex
== 0)
340 dupIndex
= p
.indexOf(dupSeparator
, 1);
344 // Ignore trailing separator (though on Windows "a:\", for
345 // example, is a valid and minimal path).
346 if (plen
> 1 && p
.charAt (plen
- 1) == separatorChar
)
348 if (! (separatorChar
== '\\' && plen
== 3 && p
.charAt (1) == ':'))
349 return p
.substring (0, plen
- 1);
355 StringBuffer newpath
= new StringBuffer(plen
);
357 while (dupIndex
!= -1)
359 newpath
.append(p
.substring(last
, dupIndex
));
360 // Ignore the duplicate path characters.
361 while (p
.charAt(dupIndex
) == separatorChar
)
364 if (dupIndex
== plen
)
365 return newpath
.toString();
367 newpath
.append(separatorChar
);
369 dupIndex
= p
.indexOf(dupSeparator
, last
);
372 // Again, ignore possible trailing separator (except special cases
373 // like "a:\" on Windows).
375 if (plen
> 1 && p
.charAt (plen
- 1) == separatorChar
)
377 if (separatorChar
== '\\' && plen
== 3 && p
.charAt (1) == ':')
384 newpath
.append(p
.substring(last
, end
));
386 return newpath
.toString();
390 * This method initializes a new <code>File</code> object to represent
391 * a file in the specified named directory. The path name to the file
392 * will be the directory name plus the separator string plus the file
393 * name. If the directory path name ends in the separator string, another
394 * separator string will still be appended.
396 * @param dirPath The path to the directory the file resides in
397 * @param name The name of the file
399 public File(String dirPath
, String name
)
402 throw new NullPointerException();
405 if (dirPath
.length() > 0)
407 // Try to be smart about the number of separator characters.
408 if (dirPath
.charAt(dirPath
.length() - 1) == separatorChar
409 || name
.length() == 0)
410 path
= normalizePath(dirPath
+ name
);
412 path
= normalizePath(dirPath
+ separatorChar
+ name
);
416 // If dirPath is empty, use a system dependant
418 // Note that the leading separators in name have
419 // to be chopped off, to prevent them forming
420 // a UNC prefix on Windows.
421 if (separatorChar
== '\\' /* TODO use ON_WINDOWS */)
424 while(name
.length() > skip
425 && (name
.charAt(skip
) == separatorChar
426 || name
.charAt(skip
) == '/'))
430 name
= name
.substring(skip
);
432 path
= normalizePath(separatorChar
+ name
);
436 path
= normalizePath(name
);
440 * This method initializes a new <code>File</code> object to represent
441 * a file in the specified directory. If the <code>directory</code>
442 * argument is <code>null</code>, the file is assumed to be in the
443 * current directory as specified by the <code>user.dir</code> system
446 * @param directory The directory this file resides in
447 * @param name The name of the file
449 public File(File directory
, String name
)
451 this (directory
== null ?
null : directory
.path
, name
);
455 * This method initializes a new <code>File</code> object to represent
456 * a file corresponding to the specified <code>file:</code> protocol URI.
459 * @throws IllegalArgumentException if the URI is not hierarchical
464 throw new NullPointerException("uri is null");
466 if (!uri
.getScheme().equals("file"))
467 throw new IllegalArgumentException("invalid uri protocol");
469 String name
= uri
.getPath();
471 throw new IllegalArgumentException("URI \"" + uri
472 + "\" is not hierarchical");
473 path
= normalizePath(name
);
477 * This method returns the path of this file as an absolute path name.
478 * If the path name is already absolute, then it is returned. Otherwise
479 * the value returned is the current directory plus the separatory
480 * string plus the path of the file. The current directory is determined
481 * from the <code>user.dir</code> system property.
483 * @return The absolute path of this file
485 public String
getAbsolutePath()
489 else if (separatorChar
== '\\'
490 && path
.length() > 0 && path
.charAt (0) == '\\')
492 // On Windows, even if the path starts with a '\\' it is not
493 // really absolute until we prefix the drive specifier from
494 // the current working directory to it.
495 return System
.getProperty ("user.dir").substring (0, 2) + path
;
497 else if (separatorChar
== '\\'
498 && path
.length() > 1 && path
.charAt (1) == ':'
499 && ((path
.charAt (0) >= 'a' && path
.charAt (0) <= 'z')
500 || (path
.charAt (0) >= 'A' && path
.charAt (0) <= 'Z')))
502 // On Windows, a process has a current working directory for
503 // each drive and a path like "G:foo\bar" would mean the
504 // absolute path "G:\wombat\foo\bar" if "\wombat" is the
505 // working directory on the G drive.
506 String drvDir
= null;
509 drvDir
= new File (path
.substring (0, 2)).getCanonicalPath();
511 catch (IOException e
)
513 drvDir
= path
.substring (0, 2) + "\\";
516 // Note: this would return "C:\\." for the path "C:.", if "\"
517 // is the working folder on the C drive, but this is
518 // consistent with what Sun's JRE 1.4.1.01 actually returns!
519 if (path
.length() > 2)
520 return drvDir
+ '\\' + path
.substring (2, path
.length());
525 return System
.getProperty ("user.dir") + separatorChar
+ path
;
529 * This method returns a <code>File</code> object representing the
530 * absolute path of this object.
532 * @return A <code>File</code> with the absolute path of the object.
536 public File
getAbsoluteFile()
538 return new File(getAbsolutePath());
542 * This method returns a canonical representation of the pathname of
543 * this file. The actual form of the canonical representation is
544 * system-dependent. On the GNU system, conversion to canonical
545 * form involves the removal of redundant separators, references to
546 * "." and "..", and symbolic links.
548 * Note that this method, unlike the other methods which return path
549 * names, can throw an IOException. This is because native method
550 * might be required in order to resolve the canonical path
552 * @exception IOException If an error occurs
554 public native String
getCanonicalPath() throws IOException
;
557 * This method returns a <code>File</code> object representing the
558 * canonical path of this object.
560 * @return A <code>File</code> instance representing the canonical path of
563 * @exception IOException If an error occurs.
567 public File
getCanonicalFile() throws IOException
569 return new File(getCanonicalPath());
573 * This method returns the name of the file. This is everything in the
574 * complete path of the file after the last instance of the separator
577 * @return The file name
579 public String
getName()
581 int nameSeqIndex
= 0;
583 if (separatorChar
== '\\' && path
.length() > 1)
585 // On Windows, ignore the drive specifier or the leading '\\'
586 // of a UNC network path, if any (a.k.a. the "prefix").
587 if ((path
.charAt (0) == '\\' && path
.charAt (1) == '\\')
588 || (((path
.charAt (0) >= 'a' && path
.charAt (0) <= 'z')
589 || (path
.charAt (0) >= 'A' && path
.charAt (0) <= 'Z'))
590 && path
.charAt (1) == ':'))
592 if (path
.length() > 2)
600 = (nameSeqIndex
> 0 ? path
.substring (nameSeqIndex
) : path
);
602 int last
= nameSeq
.lastIndexOf (separatorChar
);
604 return nameSeq
.substring (last
+ 1);
608 * This method returns a <code>String</code> the represents this file's
609 * parent. <code>null</code> is returned if the file has no parent. The
610 * parent is determined via a simple operation which removes the name
611 * after the last file separator character, as determined by the platform.
613 * @return The parent directory of this file
615 public String
getParent()
617 String prefix
= null;
618 int nameSeqIndex
= 0;
620 // The "prefix", if present, is the leading "/" on UNIX and
621 // either the drive specifier (e.g. "C:") or the leading "\\"
622 // of a UNC network path on Windows.
623 if (separatorChar
== '/' && path
.charAt (0) == '/')
628 else if (separatorChar
== '\\' && path
.length() > 1)
630 if ((path
.charAt (0) == '\\' && path
.charAt (1) == '\\')
631 || (((path
.charAt (0) >= 'a' && path
.charAt (0) <= 'z')
632 || (path
.charAt (0) >= 'A' && path
.charAt (0) <= 'Z'))
633 && path
.charAt (1) == ':'))
635 prefix
= path
.substring (0, 2);
640 // According to the JDK docs, the returned parent path is the
641 // portion of the name sequence before the last separator
642 // character, if found, prefixed by the prefix, otherwise null.
643 if (nameSeqIndex
< path
.length())
645 String nameSeq
= path
.substring (nameSeqIndex
, path
.length());
646 int last
= nameSeq
.lastIndexOf (separatorChar
);
649 else if (last
== (nameSeq
.length() - 1))
650 // Note: The path would not have a trailing separator
651 // except for cases like "C:\" on Windows (see
652 // normalizePath( )), where Sun's JRE 1.4 returns null.
658 return prefix
+ nameSeq
.substring (0, last
);
660 return nameSeq
.substring (0, last
);
663 // Sun's JRE 1.4 returns null if the prefix is the only
664 // component of the path - so "/" gives null on UNIX and
665 // "C:", "\\", etc. return null on Windows.
670 * This method returns a <code>File</code> object representing the parent
673 * @return a <code>File</code> for the parent of this object.
675 * will be returned if this object does not have a parent.
679 public File
getParentFile()
681 String parent
= getParent();
682 return parent
!= null ?
new File(parent
) : null;
686 * Returns the path name that represents this file. May be a relative
687 * or an absolute path name
689 * @return The pathname of this file
691 public String
getPath()
697 * This method returns a hash code representing this file. It is the
698 * hash code of the path of this file (as returned by <code>getPath()</code>)
699 * exclusived or-ed with the value 1234321.
701 * @return The hash code for this object
703 public int hashCode()
706 return path
.hashCode() ^
1234321;
708 return path
.toLowerCase().hashCode() ^
1234321;
712 * This method returns true if this object represents an absolute file
713 * path and false if it does not. The definition of an absolute path varies
714 * by system. As an example, on GNU systems, a path is absolute if it starts
717 * @return <code>true</code> if this object represents an absolute
718 * file name, <code>false</code> otherwise.
720 public native boolean isAbsolute();
723 * This method tests whether or not the file represented by this
724 * object is a directory.
726 private boolean internalIsDirectory()
728 return _stat (DIRECTORY
);
732 * This method tests whether or not the file represented by this object
733 * is a directory. In order for this method to return <code>true</code>,
734 * the file represented by this object must exist and be a directory.
736 * @return <code>true</code> if this file is a directory, <code>false</code>
739 * @exception SecurityException If reading of the file is not permitted
741 public boolean isDirectory()
744 return internalIsDirectory();
748 * This method tests whether or not the file represented by this object
749 * is a "plain" file. A file is a plain file if and only if it 1) Exists,
750 * 2) Is not a directory or other type of special file.
752 * @return <code>true</code> if this is a plain file, <code>false</code>
755 * @exception SecurityException If reading of the file is not permitted
757 public boolean isFile()
760 return _stat (ISFILE
);
764 * This method tests whether or not this file represents a "hidden" file.
765 * On GNU systems, a file is hidden if its name begins with a "."
766 * character. Files with these names are traditionally not shown with
767 * directory listing tools.
769 * @return <code>true</code> if the file is hidden, <code>false</code>
774 public boolean isHidden()
777 return _stat (ISHIDDEN
);
781 * This method returns the last modification time of this file. The
782 * time value returned is an abstract value that should not be interpreted
783 * as a specified time value. It is only useful for comparing to other
784 * such time values returned on the same system. In that case, the larger
785 * value indicates a more recent modification time.
787 * If the file does not exist, then a value of 0 is returned.
789 * @return The last modification time of the file
791 * @exception SecurityException If reading of the file is not permitted
793 public long lastModified()
796 return attr (MODIFIED
);
800 * This method returns the length of the file represented by this object,
801 * or 0 if the specified file does not exist.
803 * @return The length of the file
805 * @exception SecurityException If reading of the file is not permitted
810 return attr (LENGTH
);
814 * This native function actually produces the list of file in this
817 private final native Object
[] performList (FilenameFilter filter
,
818 FileFilter fileFilter
,
822 * This method returns a array of <code>String</code>'s representing the
823 * list of files is then directory represented by this object. If this
824 * object represents a non-directory file or a non-existent file, then
825 * <code>null</code> is returned. The list of files will not contain
826 * any names such as "." or ".." which indicate the current or parent
827 * directory. Also, the names are not guaranteed to be sorted.
829 * In this form of the <code>list()</code> method, a filter is specified
830 * that allows the caller to control which files are returned in the
831 * list. The <code>FilenameFilter</code> specified is called for each
832 * file returned to determine whether or not that file should be included
835 * A <code>SecurityManager</code> check is made prior to reading the
836 * directory. If read access to the directory is denied, an exception
839 * @param filter An object which will identify files to exclude from
840 * the directory listing.
842 * @return An array of files in the directory, or <code>null</code>
843 * if this object does not represent a valid directory.
845 * @exception SecurityException If read access is not allowed to the
846 * directory by the <code>SecurityManager</code>
848 public String
[] list(FilenameFilter filter
)
851 return (String
[]) performList (filter
, null, String
.class);
855 * This method returns a array of <code>String</code>'s representing the
856 * list of files is then directory represented by this object. If this
857 * object represents a non-directory file or a non-existent file, then
858 * <code>null</code> is returned. The list of files will not contain
859 * any names such as "." or ".." which indicate the current or parent
860 * directory. Also, the names are not guaranteed to be sorted.
862 * A <code>SecurityManager</code> check is made prior to reading the
863 * directory. If read access to the directory is denied, an exception
866 * @return An array of files in the directory, or <code>null</code> if
867 * this object does not represent a valid directory.
869 * @exception SecurityException If read access is not allowed to the
870 * directory by the <code>SecurityManager</code>
872 public String
[] list()
875 return (String
[]) performList (null, null, String
.class);
879 * This method returns an array of <code>File</code> objects representing
880 * all the files in the directory represented by this object. If this
881 * object does not represent a directory, <code>null</code> is returned.
882 * Each of the returned <code>File</code> object is constructed with this
883 * object as its parent.
885 * A <code>SecurityManager</code> check is made prior to reading the
886 * directory. If read access to the directory is denied, an exception
889 * @return An array of <code>File</code> objects for this directory.
891 * @exception SecurityException If the <code>SecurityManager</code> denies
892 * access to this directory.
896 public File
[] listFiles()
899 return (File
[]) performList (null, null, File
.class);
903 * This method returns an array of <code>File</code> objects representing
904 * all the files in the directory represented by this object. If this
905 * object does not represent a directory, <code>null</code> is returned.
906 * Each of the returned <code>File</code> object is constructed with this
907 * object as its parent.
909 * In this form of the <code>listFiles()</code> method, a filter is specified
910 * that allows the caller to control which files are returned in the
911 * list. The <code>FilenameFilter</code> specified is called for each
912 * file returned to determine whether or not that file should be included
915 * A <code>SecurityManager</code> check is made prior to reading the
916 * directory. If read access to the directory is denied, an exception
919 * @return An array of <code>File</code> objects for this directory.
921 * @exception SecurityException If the <code>SecurityManager</code> denies
922 * access to this directory.
926 public File
[] listFiles(FilenameFilter filter
)
929 return (File
[]) performList (filter
, null, File
.class);
933 * This method returns an array of <code>File</code> objects representing
934 * all the files in the directory represented by this object. If this
935 * object does not represent a directory, <code>null</code> is returned.
936 * Each of the returned <code>File</code> object is constructed with this
937 * object as its parent.
939 * In this form of the <code>listFiles()</code> method, a filter is specified
940 * that allows the caller to control which files are returned in the
941 * list. The <code>FileFilter</code> specified is called for each
942 * file returned to determine whether or not that file should be included
945 * A <code>SecurityManager</code> check is made prior to reading the
946 * directory. If read access to the directory is denied, an exception
949 * @return An array of <code>File</code> objects for this directory.
951 * @exception SecurityException If the <code>SecurityManager</code> denies
952 * access to this directory.
956 public File
[] listFiles(FileFilter filter
)
959 return (File
[]) performList (null, filter
, File
.class);
963 * This method returns a <code>String</code> that is the path name of the
964 * file as returned by <code>getPath</code>.
966 * @return A <code>String</code> representation of this file
968 public String
toString()
974 * @return A <code>URI</code> for this object.
978 String abspath
= getAbsolutePath();
981 abspath
= abspath
+ separator
;
985 return new URI("file", abspath
.replace(separatorChar
, '/'), null);
987 catch (URISyntaxException use
)
990 throw new RuntimeException(use
);
995 * This method returns a <code>URL</code> with the <code>file:</code>
996 * protocol that represents this file. The exact form of this URL is
999 * @return A <code>URL</code> for this object.
1001 * @exception MalformedURLException If the URL cannot be created
1004 public URL
toURL() throws MalformedURLException
1006 // On Win32, Sun's JDK returns URLs of the form "file:/c:/foo/bar.txt",
1007 // while on UNIX, it returns URLs of the form "file:/foo/bar.txt".
1008 if (separatorChar
== '\\')
1009 return new URL ("file:/" + getAbsolutePath().replace ('\\', '/')
1010 + (isDirectory() ?
"/" : ""));
1012 return new URL ("file:" + getAbsolutePath()
1013 + (isDirectory() ?
"/" : ""));
1017 * This native method actually creates the directory
1019 private final native boolean performMkdir();
1022 * This method creates a directory for the path represented by this object.
1024 * @return <code>true</code> if the directory was created,
1025 * <code>false</code> otherwise
1027 * @exception SecurityException If write access is not allowed to this file
1029 public boolean mkdir()
1032 return performMkdir();
1035 private static boolean mkdirs (File x
)
1037 if (x
.isDirectory())
1039 String p
= x
.getPath();
1040 String parent
= x
.getParent();
1052 * This method creates a directory for the path represented by this file.
1053 * It will also create any intervening parent directories if necessary.
1055 * @return <code>true</code> if the directory was created,
1056 * <code>false</code> otherwise
1058 * @exception SecurityException If write access is not allowed to this file
1060 public boolean mkdirs()
1065 return mkdirs (new File (path
));
1068 private static synchronized String
nextValue()
1070 return Long
.toString(counter
++, Character
.MAX_RADIX
);
1074 * This method creates a temporary file in the specified directory. If
1075 * the directory name is null, then this method uses the system temporary
1076 * directory. The files created are guaranteed not to currently exist and
1077 * the same file name will never be used twice in the same virtual
1079 * The system temporary directory is determined by examinging the
1080 * <code>java.io.tmpdir</code> system property.
1082 * The <code>prefix</code> parameter is a sequence of at least three
1083 * characters that are used as the start of the generated filename. The
1084 * <code>suffix</code> parameter is a sequence of characters that is used
1085 * to terminate the file name. This parameter may be <code>null</code>
1086 * and if it is, the suffix defaults to ".tmp".
1088 * If a <code>SecurityManager</code> exists, then its <code>checkWrite</code>
1089 * method is used to verify that this operation is permitted.
1091 * @param prefix The character prefix to use in generating the path name.
1092 * @param suffix The character suffix to use in generating the path name.
1093 * @param directory The directory to create the file in, or
1094 * <code>null</code> for the default temporary directory
1096 * @exception IllegalArgumentException If the patterns is not valid
1097 * @exception SecurityException If there is no permission to perform
1099 * @exception IOException If an error occurs
1103 public static File
createTempFile(String prefix
, String suffix
,
1107 // Grab the system temp directory if necessary
1108 if (directory
== null)
1110 String dirname
= tmpdir
;
1111 if (dirname
== null)
1112 throw new IOException("Cannot determine system temporary directory");
1114 directory
= new File(dirname
);
1115 if (!directory
.internalExists())
1116 throw new IOException("System temporary directory "
1117 + directory
.getName() + " does not exist.");
1118 if (!directory
.internalIsDirectory())
1119 throw new IOException("System temporary directory "
1120 + directory
.getName()
1121 + " is not really a directory.");
1124 // Check if prefix is at least 3 characters long
1125 if (prefix
.length() < 3)
1126 throw new IllegalArgumentException("Prefix too short: " + prefix
);
1128 // Set default value of suffix
1132 // Truncation rules.
1133 // `6' is the number of characters we generate.
1134 // If maxPathLen equals zero, then the system doesn't have a limit
1135 // on the file name, so there is nothing to truncate.
1136 if (maxPathLen
> 0 && prefix
.length() + 6 + suffix
.length() > maxPathLen
)
1139 if (suffix
.charAt(0) == '.')
1141 suffix
= suffix
.substring(0, suf_len
);
1142 if (prefix
.length() + 6 + suf_len
> maxPathLen
)
1143 prefix
= prefix
.substring(0, maxPathLen
- 6 - suf_len
);
1148 // How many times should we try? We choose 100.
1149 for (int i
= 0; i
< 100; ++i
)
1152 String t
= "ZZZZZZ" + nextValue();
1153 String l
= prefix
+ t
.substring(t
.length() - 6) + suffix
;
1156 f
= new File(directory
, l
);
1157 if (f
.createNewFile())
1160 catch (IOException ignored
)
1165 throw new IOException ("cannot create temporary file");
1169 * This native method sets file permissions.
1171 private native boolean setFilePermissions(boolean enable
, boolean ownerOnly
,
1175 * This method sets the owner's read permission for the File represented by
1178 * It is the same as calling <code>setReadable(readable, true)</code>.
1180 * @param <code>readable</code> <code>true</code> to set read permission,
1181 * <code>false</code> to unset the read permission.
1182 * @return <code>true</code> if the file permissions are changed,
1183 * <code>false</code> otherwise.
1184 * @exception SecurityException If write access of the file is not permitted.
1185 * @see #setReadable(boolean, boolean)
1188 public boolean setReadable(boolean readable
)
1190 return setReadable(readable
, true);
1194 * This method sets the read permissions for the File represented by
1197 * If <code>ownerOnly</code> is set to <code>true</code> then only the
1198 * read permission bit for the owner of the file is changed.
1200 * If <code>ownerOnly</code> is set to <code>false</code>, the file
1201 * permissions are changed so that the file can be read by everyone.
1203 * On unix like systems this sets the <code>user</code>, <code>group</code>
1204 * and <code>other</code> read bits and is equal to call
1205 * <code>chmod a+r</code> on the file.
1207 * @param <code>readable</code> <code>true</code> to set read permission,
1208 * <code>false</code> to unset the read permission.
1209 * @param <code>ownerOnly</code> <code>true</code> to set read permission
1210 * for owner only, <code>false</code> for all.
1211 * @return <code>true</code> if the file permissions are changed,
1212 * <code>false</code> otherwise.
1213 * @exception SecurityException If write access of the file is not permitted.
1214 * @see #setReadable(boolean)
1217 public boolean setReadable(boolean readable
, boolean ownerOnly
)
1220 return setFilePermissions(readable
, ownerOnly
, READ
);
1224 * This method sets the owner's write permission for the File represented by
1227 * It is the same as calling <code>setWritable(readable, true)</code>.
1229 * @param <code>writable</code> <code>true</code> to set write permission,
1230 * <code>false</code> to unset write permission.
1231 * @return <code>true</code> if the file permissions are changed,
1232 * <code>false</code> otherwise.
1233 * @exception SecurityException If write access of the file is not permitted.
1234 * @see #setWritable(boolean, boolean)
1237 public boolean setWritable(boolean writable
)
1239 return setWritable(writable
, true);
1243 * This method sets the write permissions for the File represented by
1246 * If <code>ownerOnly</code> is set to <code>true</code> then only the
1247 * write permission bit for the owner of the file is changed.
1249 * If <code>ownerOnly</code> is set to <code>false</code>, the file
1250 * permissions are changed so that the file can be written by everyone.
1252 * On unix like systems this set the <code>user</code>, <code>group</code>
1253 * and <code>other</code> write bits and is equal to call
1254 * <code>chmod a+w</code> on the file.
1256 * @param <code>writable</code> <code>true</code> to set write permission,
1257 * <code>false</code> to unset write permission.
1258 * @param <code>ownerOnly</code> <code>true</code> to set write permission
1259 * for owner only, <code>false</code> for all.
1260 * @return <code>true</code> if the file permissions are changed,
1261 * <code>false</code> otherwise.
1262 * @exception SecurityException If write access of the file is not permitted.
1263 * @see #setWritable(boolean)
1266 public boolean setWritable(boolean writable
, boolean ownerOnly
)
1269 return setFilePermissions(writable
, ownerOnly
, WRITE
);
1273 * This method sets the owner's execute permission for the File represented
1276 * It is the same as calling <code>setExecutable(readable, true)</code>.
1278 * @param <code>executable</code> <code>true</code> to set execute permission,
1279 * <code>false</code> to unset execute permission.
1280 * @return <code>true</code> if the file permissions are changed,
1281 * <code>false</code> otherwise.
1282 * @exception SecurityException If write access of the file is not permitted.
1283 * @see #setExecutable(boolean, boolean)
1286 public boolean setExecutable(boolean executable
)
1288 return setExecutable(executable
, true);
1292 * This method sets the execute permissions for the File represented by
1295 * If <code>ownerOnly</code> is set to <code>true</code> then only the
1296 * execute permission bit for the owner of the file is changed.
1298 * If <code>ownerOnly</code> is set to <code>false</code>, the file
1299 * permissions are changed so that the file can be executed by everyone.
1301 * On unix like systems this set the <code>user</code>, <code>group</code>
1302 * and <code>other</code> write bits and is equal to call
1303 * <code>chmod a+x</code> on the file.
1305 * @param <code>executable</code> <code>true</code> to set write permission,
1306 * <code>false</code> to unset write permission.
1307 * @param <code>ownerOnly</code> <code>true</code> to set write permission
1308 * for owner only, <code>false</code> for all.
1309 * @return <code>true</code> if the file permissions are changed,
1310 * <code>false</code> otherwise.
1311 * @exception SecurityException If write access of the file is not permitted.
1312 * @see #setExecutable(boolean)
1315 public boolean setExecutable(boolean executable
, boolean ownerOnly
)
1318 return setFilePermissions(executable
, ownerOnly
, EXEC
);
1322 * This native method sets the permissions to make the file read only.
1324 private native boolean performSetReadOnly();
1327 * This method sets the file represented by this object to be read only.
1328 * A read only file or directory cannot be modified. Please note that
1329 * GNU systems allow read only files to be deleted if the directory it
1330 * is contained in is writable.
1332 * @return <code>true</code> if the operation succeeded, <code>false</code>
1335 * @exception SecurityException If the <code>SecurityManager</code> does
1336 * not allow this operation.
1340 public boolean setReadOnly()
1342 // Do a security check before trying to do anything else.
1344 return performSetReadOnly();
1347 private static native File
[] performListRoots();
1350 * This method returns an array of filesystem roots. Some operating systems
1351 * have volume oriented filesystem. This method provides a mechanism for
1352 * determining which volumes exist. GNU systems use a single hierarchical
1353 * filesystem, so will have only one "/" filesystem root.
1355 * @return An array of <code>File</code> objects for each filesystem root
1360 public static File
[] listRoots()
1362 File
[] roots
= performListRoots();
1364 SecurityManager s
= System
.getSecurityManager();
1367 // Only return roots to which the security manager permits read access.
1368 int count
= roots
.length
;
1369 for (int i
= 0; i
< roots
.length
; i
++)
1373 s
.checkRead (roots
[i
].path
);
1375 catch (SecurityException sx
)
1381 if (count
!= roots
.length
)
1383 File
[] newRoots
= new File
[count
];
1385 for (int i
=0; i
< roots
.length
; i
++)
1387 if (roots
[i
] != null)
1388 newRoots
[k
++] = roots
[i
];
1397 * This method creates a temporary file in the system temporary directory.
1398 * The files created are guaranteed not to currently exist and the same file
1399 * name will never be used twice in the same virtual machine instance. The
1400 * system temporary directory is determined by examinging the
1401 * <code>java.io.tmpdir</code> system property.
1403 * The <code>prefix</code> parameter is a sequence of at least three
1404 * characters that are used as the start of the generated filename. The
1405 * <code>suffix</code> parameter is a sequence of characters that is used
1406 * to terminate the file name. This parameter may be <code>null</code>
1407 * and if it is, the suffix defaults to ".tmp".
1409 * If a <code>SecurityManager</code> exists, then its <code>checkWrite</code>
1410 * method is used to verify that this operation is permitted.
1412 * This method is identical to calling
1413 * <code>createTempFile(prefix, suffix, null)</code>.
1415 * @param prefix The character prefix to use in generating the path name.
1416 * @param suffix The character suffix to use in generating the path name.
1418 * @exception IllegalArgumentException If the prefix or suffix are not valid.
1419 * @exception SecurityException If there is no permission to perform
1421 * @exception IOException If an error occurs
1423 public static File
createTempFile(String prefix
, String suffix
)
1426 return createTempFile(prefix
, suffix
, null);
1430 * This method compares the specified <code>File</code> to this one
1431 * to test for equality. It does this by comparing the canonical path names
1434 * The canonical paths of the files are determined by calling the
1435 * <code>getCanonicalPath</code> method on each object.
1437 * This method returns a 0 if the specified <code>Object</code> is equal
1438 * to this one, a negative value if it is less than this one
1439 * a positive value if it is greater than this one.
1441 * @return An integer as described above
1445 public int compareTo(File other
)
1448 return path
.compareTo (other
.path
);
1450 return path
.compareToIgnoreCase (other
.path
);
1454 * This native method actually performs the rename.
1456 private native boolean performRenameTo (File dest
);
1459 * This method renames the file represented by this object to the path
1460 * of the file represented by the argument <code>File</code>.
1462 * @param dest The <code>File</code> object representing the target name
1464 * @return <code>true</code> if the rename succeeds, <code>false</code>
1467 * @exception SecurityException If write access is not allowed to the
1468 * file by the <code>SecurityMananger</code>.
1470 public synchronized boolean renameTo(File dest
)
1472 SecurityManager s
= System
.getSecurityManager();
1475 s
.checkWrite (getPath());
1476 s
.checkWrite (dest
.getPath());
1478 return performRenameTo (dest
);
1482 * This method does the actual setting of the modification time.
1484 private native boolean performSetLastModified(long time
);
1487 * This method sets the modification time on the file to the specified
1488 * value. This is specified as the number of seconds since midnight
1489 * on January 1, 1970 GMT.
1491 * @param time The desired modification time.
1493 * @return <code>true</code> if the operation succeeded, <code>false</code>
1496 * @exception IllegalArgumentException If the specified time is negative.
1497 * @exception SecurityException If the <code>SecurityManager</code> will
1498 * not allow this operation.
1502 public boolean setLastModified(long time
)
1505 throw new IllegalArgumentException("Negative modification time: " + time
);
1508 return performSetLastModified(time
);
1511 private void checkWrite()
1513 // Check the SecurityManager
1514 SecurityManager s
= System
.getSecurityManager();
1520 private void checkRead()
1522 // Check the SecurityManager
1523 SecurityManager s
= System
.getSecurityManager();
1529 private void checkExec()
1531 // Check the SecurityManager
1532 SecurityManager s
= System
.getSecurityManager();
1539 * Calling this method requests that the file represented by this object
1540 * be deleted when the virtual machine exits. Note that this request cannot
1541 * be cancelled. Also, it will only be carried out if the virtual machine
1544 * @exception SecurityException If deleting of the file is not allowed
1548 // FIXME: This should use the ShutdownHook API once we implement that.
1549 public void deleteOnExit()
1551 // Check the SecurityManager
1552 SecurityManager sm
= System
.getSecurityManager();
1554 sm
.checkDelete (getPath());
1556 DeleteFileHelper
.add(this);
1559 private void writeObject(ObjectOutputStream oos
) throws IOException
1561 oos
.defaultWriteObject();
1562 oos
.writeChar(separatorChar
);
1565 private void readObject(ObjectInputStream ois
)
1566 throws ClassNotFoundException
, IOException
1568 ois
.defaultReadObject();
1570 // If the file was from an OS with a different dir separator,
1571 // fixup the path to use the separator on this OS.
1572 char oldSeparatorChar
= ois
.readChar();
1574 if (oldSeparatorChar
!= separatorChar
)
1575 path
= path
.replace(oldSeparatorChar
, separatorChar
);