1 /*
2 * Copyright (c) 1994, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.io;
27
28 import java.net.URI;
29 import java.net.URL;
30 import java.net.MalformedURLException;
31 import java.net.URISyntaxException;
32 import java.util.List;
33 import java.util.ArrayList;
34 import java.security.AccessController;
35 import java.security.SecureRandom;
36 import java.nio.file.Path;
37 import java.nio.file.FileSystems;
38 import sun.security.action.GetPropertyAction;
39
40 /**
41 * An abstract representation of file and directory pathnames.
42 *
43 * <p> User interfaces and operating systems use system-dependent <em>pathname
44 * strings</em> to name files and directories. This class presents an
45 * abstract, system-independent view of hierarchical pathnames. An
46 * <em>abstract pathname</em> has two components:
47 *
48 * <ol>
49 * <li> An optional system-dependent <em>prefix</em> string,
50 * such as a disk-drive specifier, <code>"/"</code> for the UNIX root
51 * directory, or <code>"\\\\"</code> for a Microsoft Windows UNC pathname, and
52 * <li> A sequence of zero or more string <em>names</em>.
53 * </ol>
54 *
55 * The first name in an abstract pathname may be a directory name or, in the
56 * case of Microsoft Windows UNC pathnames, a hostname. Each subsequent name
57 * in an abstract pathname denotes a directory; the last name may denote
58 * either a directory or a file. The <em>empty</em> abstract pathname has no
59 * prefix and an empty name sequence.
60 *
61 * <p> The conversion of a pathname string to or from an abstract pathname is
62 * inherently system-dependent. When an abstract pathname is converted into a
63 * pathname string, each name is separated from the next by a single copy of
64 * the default <em>separator character</em>. The default name-separator
65 * character is defined by the system property <code>file.separator</code>, and
66 * is made available in the public static fields <code>{@link
67 * #separator}</code> and <code>{@link #separatorChar}</code> of this class.
68 * When a pathname string is converted into an abstract pathname, the names
69 * within it may be separated by the default name-separator character or by any
70 * other name-separator character that is supported by the underlying system.
71 *
72 * <p> A pathname, whether abstract or in string form, may be either
73 * <em>absolute</em> or <em>relative</em>. An absolute pathname is complete in
74 * that no other information is required in order to locate the file that it
75 * denotes. A relative pathname, in contrast, must be interpreted in terms of
76 * information taken from some other pathname. By default the classes in the
77 * <code>java.io</code> package always resolve relative pathnames against the
78 * current user directory. This directory is named by the system property
79 * <code>user.dir</code>, and is typically the directory in which the Java
80 * virtual machine was invoked.
81 *
82 * <p> The <em>parent</em> of an abstract pathname may be obtained by invoking
83 * the {@link #getParent} method of this class and consists of the pathname's
84 * prefix and each name in the pathname's name sequence except for the last.
85 * Each directory's absolute pathname is an ancestor of any <tt>File</tt>
86 * object with an absolute abstract pathname which begins with the directory's
87 * absolute pathname. For example, the directory denoted by the abstract
88 * pathname <tt>"/usr"</tt> is an ancestor of the directory denoted by the
89 * pathname <tt>"/usr/local/bin"</tt>.
90 *
91 * <p> The prefix concept is used to handle root directories on UNIX platforms,
92 * and drive specifiers, root directories and UNC pathnames on Microsoft Windows platforms,
93 * as follows:
94 *
95 * <ul>
96 *
97 * <li> For UNIX platforms, the prefix of an absolute pathname is always
98 * <code>"/"</code>. Relative pathnames have no prefix. The abstract pathname
99 * denoting the root directory has the prefix <code>"/"</code> and an empty
100 * name sequence.
101 *
102 * <li> For Microsoft Windows platforms, the prefix of a pathname that contains a drive
103 * specifier consists of the drive letter followed by <code>":"</code> and
104 * possibly followed by <code>"\\"</code> if the pathname is absolute. The
105 * prefix of a UNC pathname is <code>"\\\\"</code>; the hostname and the share
106 * name are the first two names in the name sequence. A relative pathname that
107 * does not specify a drive has no prefix.
108 *
109 * </ul>
110 *
111 * <p> Instances of this class may or may not denote an actual file-system
112 * object such as a file or a directory. If it does denote such an object
113 * then that object resides in a <i>partition</i>. A partition is an
114 * operating system-specific portion of storage for a file system. A single
115 * storage device (e.g. a physical disk-drive, flash memory, CD-ROM) may
116 * contain multiple partitions. The object, if any, will reside on the
117 * partition <a name="partName">named</a> by some ancestor of the absolute
118 * form of this pathname.
119 *
120 * <p> A file system may implement restrictions to certain operations on the
121 * actual file-system object, such as reading, writing, and executing. These
122 * restrictions are collectively known as <i>access permissions</i>. The file
123 * system may have multiple sets of access permissions on a single object.
124 * For example, one set may apply to the object's <i>owner</i>, and another
125 * may apply to all other users. The access permissions on an object may
126 * cause some methods in this class to fail.
127 *
128 * <p> Instances of the <code>File</code> class are immutable; that is, once
129 * created, the abstract pathname represented by a <code>File</code> object
130 * will never change.
131 *
132 * <h3>Interoperability with {@code java.nio.file} package</h3>
133 *
134 * <p> The <a href="../../java/nio/file/package-summary.html">{@code java.nio.file}</a>
135 * package defines interfaces and classes for the Java virtual machine to access
136 * files, file attributes, and file systems. This API may be used to overcome
137 * many of the limitations of the {@code java.io.File} class.
138 * The {@link #toPath toPath} method may be used to obtain a {@link
139 * Path} that uses the abstract path represented by a {@code File} object to
140 * locate a file. The resulting {@code Path} may be used with the {@link
141 * java.nio.file.Files} class to provide more efficient and extensive access to
142 * additional file operations, file attributes, and I/O exceptions to help
143 * diagnose errors when an operation on a file fails.
144 *
145 * @author unascribed
146 * @since JDK1.0
147 */
148
149 public class File
150 implements Serializable, Comparable<File>
151 {
152
153 /**
154 * The FileSystem object representing the platform's local file system.
155 */
156 private static final FileSystem fs = DefaultFileSystem.getFileSystem();
157
158 /**
159 * This abstract pathname's normalized pathname string. A normalized
160 * pathname string uses the default name-separator character and does not
161 * contain any duplicate or redundant separators.
162 *
163 * @serial
164 */
165 private final String path;
166
167 /**
168 * Enum type that indicates the status of a file path.
169 */
170 private static enum PathStatus { INVALID, CHECKED };
171
172 /**
173 * The flag indicating whether the file path is invalid.
174 */
175 private transient PathStatus status = null;
176
177 /**
178 * Check if the file has an invalid path. Currently, the inspection of
179 * a file path is very limited, and it only covers Nul character check.
180 * Returning true means the path is definitely invalid/garbage. But
181 * returning false does not guarantee that the path is valid.
182 *
183 * @return true if the file path is invalid.
184 */
185 final boolean isInvalid() {
186 if (status == null) {
187 status = (this.path.indexOf('\u0000') < 0) ? PathStatus.CHECKED
188 : PathStatus.INVALID;
189 }
190 return status == PathStatus.INVALID;
191 }
192
193 /**
194 * The length of this abstract pathname's prefix, or zero if it has no
195 * prefix.
196 */
197 private final transient int prefixLength;
198
199 /**
200 * Returns the length of this abstract pathname's prefix.
201 * For use by FileSystem classes.
202 */
203 int getPrefixLength() {
204 return prefixLength;
205 }
206
207 /**
208 * The system-dependent default name-separator character. This field is
209 * initialized to contain the first character of the value of the system
210 * property <code>file.separator</code>. On UNIX systems the value of this
211 * field is <code>'/'</code>; on Microsoft Windows systems it is <code>'\\'</code>.
212 *
213 * @see java.lang.System#getProperty(java.lang.String)
214 */
215 public static final char separatorChar = fs.getSeparator();
216
217 /**
218 * The system-dependent default name-separator character, represented as a
219 * string for convenience. This string contains a single character, namely
220 * <code>{@link #separatorChar}</code>.
221 */
222 public static final String separator = "" + separatorChar;
223
224 /**
225 * The system-dependent path-separator character. This field is
226 * initialized to contain the first character of the value of the system
227 * property <code>path.separator</code>. This character is used to
228 * separate filenames in a sequence of files given as a <em>path list</em>.
229 * On UNIX systems, this character is <code>':'</code>; on Microsoft Windows systems it
230 * is <code>';'</code>.
231 *
232 * @see java.lang.System#getProperty(java.lang.String)
233 */
234 public static final char pathSeparatorChar = fs.getPathSeparator();
235
236 /**
237 * The system-dependent path-separator character, represented as a string
238 * for convenience. This string contains a single character, namely
239 * <code>{@link #pathSeparatorChar}</code>.
240 */
241 public static final String pathSeparator = "" + pathSeparatorChar;
242
243
244 /* -- Constructors -- */
245
246 /**
247 * Internal constructor for already-normalized pathname strings.
248 */
249 private File(String pathname, int prefixLength) {
250 this.path = pathname;
251 this.prefixLength = prefixLength;
252 }
253
254 /**
255 * Internal constructor for already-normalized pathname strings.
256 * The parameter order is used to disambiguate this method from the
257 * public(File, String) constructor.
258 */
259 private File(String child, File parent) {
260 assert parent.path != null;
261 assert (!parent.path.equals(""));
262 this.path = fs.resolve(parent.path, child);
263 this.prefixLength = parent.prefixLength;
264 }
265
266 /**
267 * Creates a new <code>File</code> instance by converting the given
268 * pathname string into an abstract pathname. If the given string is
269 * the empty string, then the result is the empty abstract pathname.
270 *
271 * @param pathname A pathname string
272 * @throws NullPointerException
273 * If the <code>pathname</code> argument is <code>null</code>
274 */
275 public File(String pathname) {
276 if (pathname == null) {
277 throw new NullPointerException();
278 }
279 this.path = fs.normalize(pathname);
280 this.prefixLength = fs.prefixLength(this.path);
281 }
282
283 /* Note: The two-argument File constructors do not interpret an empty
284 parent abstract pathname as the current user directory. An empty parent
285 instead causes the child to be resolved against the system-dependent
286 directory defined by the FileSystem.getDefaultParent method. On Unix
287 this default is "/", while on Microsoft Windows it is "\\". This is required for
288 compatibility with the original behavior of this class. */
289
290 /**
291 * Creates a new <code>File</code> instance from a parent pathname string
292 * and a child pathname string.
293 *
294 * <p> If <code>parent</code> is <code>null</code> then the new
295 * <code>File</code> instance is created as if by invoking the
296 * single-argument <code>File</code> constructor on the given
297 * <code>child</code> pathname string.
298 *
299 * <p> Otherwise the <code>parent</code> pathname string is taken to denote
300 * a directory, and the <code>child</code> pathname string is taken to
301 * denote either a directory or a file. If the <code>child</code> pathname
302 * string is absolute then it is converted into a relative pathname in a
303 * system-dependent way. If <code>parent</code> is the empty string then
304 * the new <code>File</code> instance is created by converting
305 * <code>child</code> into an abstract pathname and resolving the result
306 * against a system-dependent default directory. Otherwise each pathname
307 * string is converted into an abstract pathname and the child abstract
308 * pathname is resolved against the parent.
309 *
310 * @param parent The parent pathname string
311 * @param child The child pathname string
312 * @throws NullPointerException
313 * If <code>child</code> is <code>null</code>
314 */
315 public File(String parent, String child) {
316 if (child == null) {
317 throw new NullPointerException();
318 }
319 if (parent != null) {
320 if (parent.equals("")) {
321 this.path = fs.resolve(fs.getDefaultParent(),
322 fs.normalize(child));
323 } else {
324 this.path = fs.resolve(fs.normalize(parent),
325 fs.normalize(child));
326 }
327 } else {
328 this.path = fs.normalize(child);
329 }
330 this.prefixLength = fs.prefixLength(this.path);
331 }
332
333 /**
334 * Creates a new <code>File</code> instance from a parent abstract
335 * pathname and a child pathname string.
336 *
337 * <p> If <code>parent</code> is <code>null</code> then the new
338 * <code>File</code> instance is created as if by invoking the
339 * single-argument <code>File</code> constructor on the given
340 * <code>child</code> pathname string.
341 *
342 * <p> Otherwise the <code>parent</code> abstract pathname is taken to
343 * denote a directory, and the <code>child</code> pathname string is taken
344 * to denote either a directory or a file. If the <code>child</code>
345 * pathname string is absolute then it is converted into a relative
346 * pathname in a system-dependent way. If <code>parent</code> is the empty
347 * abstract pathname then the new <code>File</code> instance is created by
348 * converting <code>child</code> into an abstract pathname and resolving
349 * the result against a system-dependent default directory. Otherwise each
350 * pathname string is converted into an abstract pathname and the child
351 * abstract pathname is resolved against the parent.
352 *
353 * @param parent The parent abstract pathname
354 * @param child The child pathname string
355 * @throws NullPointerException
356 * If <code>child</code> is <code>null</code>
357 */
358 public File(File parent, String child) {
359 if (child == null) {
360 throw new NullPointerException();
361 }
362 if (parent != null) {
363 if (parent.path.equals("")) {
364 this.path = fs.resolve(fs.getDefaultParent(),
365 fs.normalize(child));
366 } else {
367 this.path = fs.resolve(parent.path,
368 fs.normalize(child));
369 }
370 } else {
371 this.path = fs.normalize(child);
372 }
373 this.prefixLength = fs.prefixLength(this.path);
374 }
375
376 /**
377 * Creates a new <tt>File</tt> instance by converting the given
378 * <tt>file:</tt> URI into an abstract pathname.
379 *
380 * <p> The exact form of a <tt>file:</tt> URI is system-dependent, hence
381 * the transformation performed by this constructor is also
382 * system-dependent.
383 *
384 * <p> For a given abstract pathname <i>f</i> it is guaranteed that
385 *
386 * <blockquote><tt>
387 * new File(</tt><i> f</i><tt>.{@link #toURI() toURI}()).equals(</tt><i> f</i><tt>.{@link #getAbsoluteFile() getAbsoluteFile}())
388 * </tt></blockquote>
389 *
390 * so long as the original abstract pathname, the URI, and the new abstract
391 * pathname are all created in (possibly different invocations of) the same
392 * Java virtual machine. This relationship typically does not hold,
393 * however, when a <tt>file:</tt> URI that is created in a virtual machine
394 * on one operating system is converted into an abstract pathname in a
395 * virtual machine on a different operating system.
396 *
397 * @param uri
398 * An absolute, hierarchical URI with a scheme equal to
399 * <tt>"file"</tt>, a non-empty path component, and undefined
400 * authority, query, and fragment components
401 *
402 * @throws NullPointerException
403 * If <tt>uri</tt> is <tt>null</tt>
404 *
405 * @throws IllegalArgumentException
406 * If the preconditions on the parameter do not hold
407 *
408 * @see #toURI()
409 * @see java.net.URI
410 * @since 1.4
411 */
412 public File(URI uri) {
413
414 // Check our many preconditions
415 if (!uri.isAbsolute())
416 throw new IllegalArgumentException("URI is not absolute");
417 if (uri.isOpaque())
418 throw new IllegalArgumentException("URI is not hierarchical");
419 String scheme = uri.getScheme();
420 if ((scheme == null) || !scheme.equalsIgnoreCase("file"))
421 throw new IllegalArgumentException("URI scheme is not \"file\"");
422 if (uri.getAuthority() != null)
423 throw new IllegalArgumentException("URI has an authority component");
424 if (uri.getFragment() != null)
425 throw new IllegalArgumentException("URI has a fragment component");
426 if (uri.getQuery() != null)
427 throw new IllegalArgumentException("URI has a query component");
428 String p = uri.getPath();
429 if (p.equals(""))
430 throw new IllegalArgumentException("URI path component is empty");
431
432 // Okay, now initialize
433 p = fs.fromURIPath(p);
434 if (File.separatorChar != '/')
435 p = p.replace('/', File.separatorChar);
436 this.path = fs.normalize(p);
437 this.prefixLength = fs.prefixLength(this.path);
438 }
439
440
441 /* -- Path-component accessors -- */
442
443 /**
444 * Returns the name of the file or directory denoted by this abstract
445 * pathname. This is just the last name in the pathname's name
446 * sequence. If the pathname's name sequence is empty, then the empty
447 * string is returned.
448 *
449 * @return The name of the file or directory denoted by this abstract
450 * pathname, or the empty string if this pathname's name sequence
451 * is empty
452 */
453 public String getName() {
454 int index = path.lastIndexOf(separatorChar);
455 if (index < prefixLength) return path.substring(prefixLength);
456 return path.substring(index + 1);
457 }
458
459 /**
460 * Returns the pathname string of this abstract pathname's parent, or
461 * <code>null</code> if this pathname does not name a parent directory.
462 *
463 * <p> The <em>parent</em> of an abstract pathname consists of the
464 * pathname's prefix, if any, and each name in the pathname's name
465 * sequence except for the last. If the name sequence is empty then
466 * the pathname does not name a parent directory.
467 *
468 * @return The pathname string of the parent directory named by this
469 * abstract pathname, or <code>null</code> if this pathname
470 * does not name a parent
471 */
472 public String getParent() {
473 int index = path.lastIndexOf(separatorChar);
474 if (index < prefixLength) {
475 if ((prefixLength > 0) && (path.length() > prefixLength))
476 return path.substring(0, prefixLength);
477 return null;
478 }
479 return path.substring(0, index);
480 }
481
482 /**
483 * Returns the abstract pathname of this abstract pathname's parent,
484 * or <code>null</code> if this pathname does not name a parent
485 * directory.
486 *
487 * <p> The <em>parent</em> of an abstract pathname consists of the
488 * pathname's prefix, if any, and each name in the pathname's name
489 * sequence except for the last. If the name sequence is empty then
490 * the pathname does not name a parent directory.
491 *
492 * @return The abstract pathname of the parent directory named by this
493 * abstract pathname, or <code>null</code> if this pathname
494 * does not name a parent
495 *
496 * @since 1.2
497 */
498 public File getParentFile() {
499 String p = this.getParent();
500 if (p == null) return null;
501 return new File(p, this.prefixLength);
502 }
503
504 /**
505 * Converts this abstract pathname into a pathname string. The resulting
506 * string uses the {@link #separator default name-separator character} to
507 * separate the names in the name sequence.
508 *
509 * @return The string form of this abstract pathname
510 */
511 public String getPath() {
512 return path;
513 }
514
515
516 /* -- Path operations -- */
517
518 /**
519 * Tests whether this abstract pathname is absolute. The definition of
520 * absolute pathname is system dependent. On UNIX systems, a pathname is
521 * absolute if its prefix is <code>"/"</code>. On Microsoft Windows systems, a
522 * pathname is absolute if its prefix is a drive specifier followed by
523 * <code>"\\"</code>, or if its prefix is <code>"\\\\"</code>.
524 *
525 * @return <code>true</code> if this abstract pathname is absolute,
526 * <code>false</code> otherwise
527 */
528 public boolean isAbsolute() {
529 return fs.isAbsolute(this);
530 }
531
532 /**
533 * Returns the absolute pathname string of this abstract pathname.
534 *
535 * <p> If this abstract pathname is already absolute, then the pathname
536 * string is simply returned as if by the <code>{@link #getPath}</code>
537 * method. If this abstract pathname is the empty abstract pathname then
538 * the pathname string of the current user directory, which is named by the
539 * system property <code>user.dir</code>, is returned. Otherwise this
540 * pathname is resolved in a system-dependent way. On UNIX systems, a
541 * relative pathname is made absolute by resolving it against the current
542 * user directory. On Microsoft Windows systems, a relative pathname is made absolute
543 * by resolving it against the current directory of the drive named by the
544 * pathname, if any; if not, it is resolved against the current user
545 * directory.
546 *
547 * @return The absolute pathname string denoting the same file or
548 * directory as this abstract pathname
549 *
550 * @throws SecurityException
551 * If a required system property value cannot be accessed.
552 *
553 * @see java.io.File#isAbsolute()
554 */
555 public String getAbsolutePath() {
556 return fs.resolve(this);
557 }
558
559 /**
560 * Returns the absolute form of this abstract pathname. Equivalent to
561 * <code>new File(this.{@link #getAbsolutePath})</code>.
562 *
563 * @return The absolute abstract pathname denoting the same file or
564 * directory as this abstract pathname
565 *
566 * @throws SecurityException
567 * If a required system property value cannot be accessed.
568 *
569 * @since 1.2
570 */
571 public File getAbsoluteFile() {
572 String absPath = getAbsolutePath();
573 return new File(absPath, fs.prefixLength(absPath));
574 }
575
576 /**
577 * Returns the canonical pathname string of this abstract pathname.
578 *
579 * <p> A canonical pathname is both absolute and unique. The precise
580 * definition of canonical form is system-dependent. This method first
581 * converts this pathname to absolute form if necessary, as if by invoking the
582 * {@link #getAbsolutePath} method, and then maps it to its unique form in a
583 * system-dependent way. This typically involves removing redundant names
584 * such as <tt>"."</tt> and <tt>".."</tt> from the pathname, resolving
585 * symbolic links (on UNIX platforms), and converting drive letters to a
586 * standard case (on Microsoft Windows platforms).
587 *
588 * <p> Every pathname that denotes an existing file or directory has a
589 * unique canonical form. Every pathname that denotes a nonexistent file
590 * or directory also has a unique canonical form. The canonical form of
591 * the pathname of a nonexistent file or directory may be different from
592 * the canonical form of the same pathname after the file or directory is
593 * created. Similarly, the canonical form of the pathname of an existing
594 * file or directory may be different from the canonical form of the same
595 * pathname after the file or directory is deleted.
596 *
597 * @return The canonical pathname string denoting the same file or
598 * directory as this abstract pathname
599 *
600 * @throws IOException
601 * If an I/O error occurs, which is possible because the
602 * construction of the canonical pathname may require
603 * filesystem queries
604 *
605 * @throws SecurityException
606 * If a required system property value cannot be accessed, or
607 * if a security manager exists and its <code>{@link
608 * java.lang.SecurityManager#checkRead}</code> method denies
609 * read access to the file
610 *
611 * @since JDK1.1
612 * @see Path#toRealPath
613 */
614 public String getCanonicalPath() throws IOException {
615 if (isInvalid()) {
616 throw new IOException("Invalid file path");
617 }
618 return fs.canonicalize(fs.resolve(this));
619 }
620
621 /**
622 * Returns the canonical form of this abstract pathname. Equivalent to
623 * <code>new File(this.{@link #getCanonicalPath})</code>.
624 *
625 * @return The canonical pathname string denoting the same file or
626 * directory as this abstract pathname
627 *
628 * @throws IOException
629 * If an I/O error occurs, which is possible because the
630 * construction of the canonical pathname may require
631 * filesystem queries
632 *
633 * @throws SecurityException
634 * If a required system property value cannot be accessed, or
635 * if a security manager exists and its <code>{@link
636 * java.lang.SecurityManager#checkRead}</code> method denies
637 * read access to the file
638 *
639 * @since 1.2
640 * @see Path#toRealPath
641 */
642 public File getCanonicalFile() throws IOException {
643 String canonPath = getCanonicalPath();
644 return new File(canonPath, fs.prefixLength(canonPath));
645 }
646
647 private static String slashify(String path, boolean isDirectory) {
648 String p = path;
649 if (File.separatorChar != '/')
650 p = p.replace(File.separatorChar, '/');
651 if (!p.startsWith("/"))
652 p = "/" + p;
653 if (!p.endsWith("/") && isDirectory)
654 p = p + "/";
655 return p;
656 }
657
658 /**
659 * Converts this abstract pathname into a <code>file:</code> URL. The
660 * exact form of the URL is system-dependent. If it can be determined that
661 * the file denoted by this abstract pathname is a directory, then the
662 * resulting URL will end with a slash.
663 *
664 * @return A URL object representing the equivalent file URL
665 *
666 * @throws MalformedURLException
667 * If the path cannot be parsed as a URL
668 *
669 * @see #toURI()
670 * @see java.net.URI
671 * @see java.net.URI#toURL()
672 * @see java.net.URL
673 * @since 1.2
674 *
675 * @deprecated This method does not automatically escape characters that
676 * are illegal in URLs. It is recommended that new code convert an
677 * abstract pathname into a URL by first converting it into a URI, via the
678 * {@link #toURI() toURI} method, and then converting the URI into a URL
679 * via the {@link java.net.URI#toURL() URI.toURL} method.
680 */
681 @Deprecated
682 public URL toURL() throws MalformedURLException {
683 if (isInvalid()) {
684 throw new MalformedURLException("Invalid file path");
685 }
686 return new URL("file", "", slashify(getAbsolutePath(), isDirectory()));
687 }
688
689 /**
690 * Constructs a <tt>file:</tt> URI that represents this abstract pathname.
691 *
692 * <p> The exact form of the URI is system-dependent. If it can be
693 * determined that the file denoted by this abstract pathname is a
694 * directory, then the resulting URI will end with a slash.
695 *
696 * <p> For a given abstract pathname <i>f</i>, it is guaranteed that
697 *
698 * <blockquote><tt>
699 * new {@link #File(java.net.URI) File}(</tt><i> f</i><tt>.toURI()).equals(</tt><i> f</i><tt>.{@link #getAbsoluteFile() getAbsoluteFile}())
700 * </tt></blockquote>
701 *
702 * so long as the original abstract pathname, the URI, and the new abstract
703 * pathname are all created in (possibly different invocations of) the same
704 * Java virtual machine. Due to the system-dependent nature of abstract
705 * pathnames, however, this relationship typically does not hold when a
706 * <tt>file:</tt> URI that is created in a virtual machine on one operating
707 * system is converted into an abstract pathname in a virtual machine on a
708 * different operating system.
709 *
710 * <p> Note that when this abstract pathname represents a UNC pathname then
711 * all components of the UNC (including the server name component) are encoded
712 * in the {@code URI} path. The authority component is undefined, meaning
713 * that it is represented as {@code null}. The {@link Path} class defines the
714 * {@link Path#toUri toUri} method to encode the server name in the authority
715 * component of the resulting {@code URI}. The {@link #toPath toPath} method
716 * may be used to obtain a {@code Path} representing this abstract pathname.
717 *
718 * @return An absolute, hierarchical URI with a scheme equal to
719 * <tt>"file"</tt>, a path representing this abstract pathname,
720 * and undefined authority, query, and fragment components
721 * @throws SecurityException If a required system property value cannot
722 * be accessed.
723 *
724 * @see #File(java.net.URI)
725 * @see java.net.URI
726 * @see java.net.URI#toURL()
727 * @since 1.4
728 */
729 public URI toURI() {
730 try {
731 File f = getAbsoluteFile();
732 String sp = slashify(f.getPath(), f.isDirectory());
733 if (sp.startsWith("//"))
734 sp = "//" + sp;
735 return new URI("file", null, sp, null);
736 } catch (URISyntaxException x) {
737 throw new Error(x); // Can't happen
738 }
739 }
740
741
742 /* -- Attribute accessors -- */
743
744 /**
745 * Tests whether the application can read the file denoted by this
746 * abstract pathname. On some platforms it may be possible to start the
747 * Java virtual machine with special privileges that allow it to read
748 * files that are marked as unreadable. Consequently this method may return
749 * {@code true} even though the file does not have read permissions.
750 *
751 * @return <code>true</code> if and only if the file specified by this
752 * abstract pathname exists <em>and</em> can be read by the
753 * application; <code>false</code> otherwise
754 *
755 * @throws SecurityException
756 * If a security manager exists and its <code>{@link
757 * java.lang.SecurityManager#checkRead(java.lang.String)}</code>
758 * method denies read access to the file
759 */
760 public boolean canRead() {
761 SecurityManager security = System.getSecurityManager();
762 if (security != null) {
763 security.checkRead(path);
764 }
765 if (isInvalid()) {
766 return false;
767 }
768 return fs.checkAccess(this, FileSystem.ACCESS_READ);
769 }
770
771 /**
772 * Tests whether the application can modify the file denoted by this
773 * abstract pathname. On some platforms it may be possible to start the
774 * Java virtual machine with special privileges that allow it to modify
775 * files that are marked read-only. Consequently this method may return
776 * {@code true} even though the file is marked read-only.
777 *
778 * @return <code>true</code> if and only if the file system actually
779 * contains a file denoted by this abstract pathname <em>and</em>
780 * the application is allowed to write to the file;
781 * <code>false</code> otherwise.
782 *
783 * @throws SecurityException
784 * If a security manager exists and its <code>{@link
785 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
786 * method denies write access to the file
787 */
788 public boolean canWrite() {
789 SecurityManager security = System.getSecurityManager();
790 if (security != null) {
791 security.checkWrite(path);
792 }
793 if (isInvalid()) {
794 return false;
795 }
796 return fs.checkAccess(this, FileSystem.ACCESS_WRITE);
797 }
798
799 /**
800 * Tests whether the file or directory denoted by this abstract pathname
801 * exists.
802 *
803 * @return <code>true</code> if and only if the file or directory denoted
804 * by this abstract pathname exists; <code>false</code> otherwise
805 *
806 * @throws SecurityException
807 * If a security manager exists and its <code>{@link
808 * java.lang.SecurityManager#checkRead(java.lang.String)}</code>
809 * method denies read access to the file or directory
810 */
811 public boolean exists() {
812 SecurityManager security = System.getSecurityManager();
813 if (security != null) {
814 security.checkRead(path);
815 }
816 if (isInvalid()) {
817 return false;
818 }
819 return ((fs.getBooleanAttributes(this) & FileSystem.BA_EXISTS) != 0);
820 }
821
822 /**
823 * Tests whether the file denoted by this abstract pathname is a
824 * directory.
825 *
826 * <p> Where it is required to distinguish an I/O exception from the case
827 * that the file is not a directory, or where several attributes of the
828 * same file are required at the same time, then the {@link
829 * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
830 * Files.readAttributes} method may be used.
831 *
832 * @return <code>true</code> if and only if the file denoted by this
833 * abstract pathname exists <em>and</em> is a directory;
834 * <code>false</code> otherwise
835 *
836 * @throws SecurityException
837 * If a security manager exists and its <code>{@link
838 * java.lang.SecurityManager#checkRead(java.lang.String)}</code>
839 * method denies read access to the file
840 */
841 public boolean isDirectory() {
842 SecurityManager security = System.getSecurityManager();
843 if (security != null) {
844 security.checkRead(path);
845 }
846 if (isInvalid()) {
847 return false;
848 }
849 return ((fs.getBooleanAttributes(this) & FileSystem.BA_DIRECTORY)
850 != 0);
851 }
852
853 /**
854 * Tests whether the file denoted by this abstract pathname is a normal
855 * file. A file is <em>normal</em> if it is not a directory and, in
856 * addition, satisfies other system-dependent criteria. Any non-directory
857 * file created by a Java application is guaranteed to be a normal file.
858 *
859 * <p> Where it is required to distinguish an I/O exception from the case
860 * that the file is not a normal file, or where several attributes of the
861 * same file are required at the same time, then the {@link
862 * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
863 * Files.readAttributes} method may be used.
864 *
865 * @return <code>true</code> if and only if the file denoted by this
866 * abstract pathname exists <em>and</em> is a normal file;
867 * <code>false</code> otherwise
868 *
869 * @throws SecurityException
870 * If a security manager exists and its <code>{@link
871 * java.lang.SecurityManager#checkRead(java.lang.String)}</code>
872 * method denies read access to the file
873 */
874 public boolean isFile() {
875 SecurityManager security = System.getSecurityManager();
876 if (security != null) {
877 security.checkRead(path);
878 }
879 if (isInvalid()) {
880 return false;
881 }
882 return ((fs.getBooleanAttributes(this) & FileSystem.BA_REGULAR) != 0);
883 }
884
885 /**
886 * Tests whether the file named by this abstract pathname is a hidden
887 * file. The exact definition of <em>hidden</em> is system-dependent. On
888 * UNIX systems, a file is considered to be hidden if its name begins with
889 * a period character (<code>'.'</code>). On Microsoft Windows systems, a file is
890 * considered to be hidden if it has been marked as such in the filesystem.
891 *
892 * @return <code>true</code> if and only if the file denoted by this
893 * abstract pathname is hidden according to the conventions of the
894 * underlying platform
895 *
896 * @throws SecurityException
897 * If a security manager exists and its <code>{@link
898 * java.lang.SecurityManager#checkRead(java.lang.String)}</code>
899 * method denies read access to the file
900 *
901 * @since 1.2
902 */
903 public boolean isHidden() {
904 SecurityManager security = System.getSecurityManager();
905 if (security != null) {
906 security.checkRead(path);
907 }
908 if (isInvalid()) {
909 return false;
910 }
911 return ((fs.getBooleanAttributes(this) & FileSystem.BA_HIDDEN) != 0);
912 }
913
914 /**
915 * Returns the time that the file denoted by this abstract pathname was
916 * last modified.
917 *
918 * <p> Where it is required to distinguish an I/O exception from the case
919 * where {@code 0L} is returned, or where several attributes of the
920 * same file are required at the same time, or where the time of last
921 * access or the creation time are required, then the {@link
922 * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
923 * Files.readAttributes} method may be used.
924 *
925 * @return A <code>long</code> value representing the time the file was
926 * last modified, measured in milliseconds since the epoch
927 * (00:00:00 GMT, January 1, 1970), or <code>0L</code> if the
928 * file does not exist or if an I/O error occurs
929 *
930 * @throws SecurityException
931 * If a security manager exists and its <code>{@link
932 * java.lang.SecurityManager#checkRead(java.lang.String)}</code>
933 * method denies read access to the file
934 */
935 public long lastModified() {
936 SecurityManager security = System.getSecurityManager();
937 if (security != null) {
938 security.checkRead(path);
939 }
940 if (isInvalid()) {
941 return 0L;
942 }
943 return fs.getLastModifiedTime(this);
944 }
945
946 /**
947 * Returns the length of the file denoted by this abstract pathname.
948 * The return value is unspecified if this pathname denotes a directory.
949 *
950 * <p> Where it is required to distinguish an I/O exception from the case
951 * that {@code 0L} is returned, or where several attributes of the same file
952 * are required at the same time, then the {@link
953 * java.nio.file.Files#readAttributes(Path,Class,LinkOption[])
954 * Files.readAttributes} method may be used.
955 *
956 * @return The length, in bytes, of the file denoted by this abstract
957 * pathname, or <code>0L</code> if the file does not exist. Some
958 * operating systems may return <code>0L</code> for pathnames
959 * denoting system-dependent entities such as devices or pipes.
960 *
961 * @throws SecurityException
962 * If a security manager exists and its <code>{@link
963 * java.lang.SecurityManager#checkRead(java.lang.String)}</code>
964 * method denies read access to the file
965 */
966 public long length() {
967 SecurityManager security = System.getSecurityManager();
968 if (security != null) {
969 security.checkRead(path);
970 }
971 if (isInvalid()) {
972 return 0L;
973 }
974 return fs.getLength(this);
975 }
976
977
978 /* -- File operations -- */
979
980 /**
981 * Atomically creates a new, empty file named by this abstract pathname if
982 * and only if a file with this name does not yet exist. The check for the
983 * existence of the file and the creation of the file if it does not exist
984 * are a single operation that is atomic with respect to all other
985 * filesystem activities that might affect the file.
986 * <P>
987 * Note: this method should <i>not</i> be used for file-locking, as
988 * the resulting protocol cannot be made to work reliably. The
989 * {@link java.nio.channels.FileLock FileLock}
990 * facility should be used instead.
991 *
992 * @return <code>true</code> if the named file does not exist and was
993 * successfully created; <code>false</code> if the named file
994 * already exists
995 *
996 * @throws IOException
997 * If an I/O error occurred
998 *
999 * @throws SecurityException
1000 * If a security manager exists and its <code>{@link
1001 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1002 * method denies write access to the file
1003 *
1004 * @since 1.2
1005 */
1006 public boolean createNewFile() throws IOException {
1007 SecurityManager security = System.getSecurityManager();
1008 if (security != null) security.checkWrite(path);
1009 if (isInvalid()) {
1010 throw new IOException("Invalid file path");
1011 }
1012 return fs.createFileExclusively(path);
1013 }
1014
1015 /**
1016 * Deletes the file or directory denoted by this abstract pathname. If
1017 * this pathname denotes a directory, then the directory must be empty in
1018 * order to be deleted.
1019 *
1020 * <p> Note that the {@link java.nio.file.Files} class defines the {@link
1021 * java.nio.file.Files#delete(Path) delete} method to throw an {@link IOException}
1022 * when a file cannot be deleted. This is useful for error reporting and to
1023 * diagnose why a file cannot be deleted.
1024 *
1025 * @return <code>true</code> if and only if the file or directory is
1026 * successfully deleted; <code>false</code> otherwise
1027 *
1028 * @throws SecurityException
1029 * If a security manager exists and its <code>{@link
1030 * java.lang.SecurityManager#checkDelete}</code> method denies
1031 * delete access to the file
1032 */
1033 public boolean delete() {
1034 SecurityManager security = System.getSecurityManager();
1035 if (security != null) {
1036 security.checkDelete(path);
1037 }
1038 if (isInvalid()) {
1039 return false;
1040 }
1041 return fs.delete(this);
1042 }
1043
1044 /**
1045 * Requests that the file or directory denoted by this abstract
1046 * pathname be deleted when the virtual machine terminates.
1047 * Files (or directories) are deleted in the reverse order that
1048 * they are registered. Invoking this method to delete a file or
1049 * directory that is already registered for deletion has no effect.
1050 * Deletion will be attempted only for normal termination of the
1051 * virtual machine, as defined by the Java Language Specification.
1052 *
1053 * <p> Once deletion has been requested, it is not possible to cancel the
1054 * request. This method should therefore be used with care.
1055 *
1056 * <P>
1057 * Note: this method should <i>not</i> be used for file-locking, as
1058 * the resulting protocol cannot be made to work reliably. The
1059 * {@link java.nio.channels.FileLock FileLock}
1060 * facility should be used instead.
1061 *
1062 * @throws SecurityException
1063 * If a security manager exists and its <code>{@link
1064 * java.lang.SecurityManager#checkDelete}</code> method denies
1065 * delete access to the file
1066 *
1067 * @see #delete
1068 *
1069 * @since 1.2
1070 */
1071 public void deleteOnExit() {
1072 SecurityManager security = System.getSecurityManager();
1073 if (security != null) {
1074 security.checkDelete(path);
1075 }
1076 if (isInvalid()) {
1077 return;
1078 }
1079 DeleteOnExitHook.add(path);
1080 }
1081
1082 /**
1083 * Returns an array of strings naming the files and directories in the
1084 * directory denoted by this abstract pathname.
1085 *
1086 * <p> If this abstract pathname does not denote a directory, then this
1087 * method returns {@code null}. Otherwise an array of strings is
1088 * returned, one for each file or directory in the directory. Names
1089 * denoting the directory itself and the directory's parent directory are
1090 * not included in the result. Each string is a file name rather than a
1091 * complete path.
1092 *
1093 * <p> There is no guarantee that the name strings in the resulting array
1094 * will appear in any specific order; they are not, in particular,
1095 * guaranteed to appear in alphabetical order.
1096 *
1097 * <p> Note that the {@link java.nio.file.Files} class defines the {@link
1098 * java.nio.file.Files#newDirectoryStream(Path) newDirectoryStream} method to
1099 * open a directory and iterate over the names of the files in the directory.
1100 * This may use less resources when working with very large directories, and
1101 * may be more responsive when working with remote directories.
1102 *
1103 * @return An array of strings naming the files and directories in the
1104 * directory denoted by this abstract pathname. The array will be
1105 * empty if the directory is empty. Returns {@code null} if
1106 * this abstract pathname does not denote a directory, or if an
1107 * I/O error occurs.
1108 *
1109 * @throws SecurityException
1110 * If a security manager exists and its {@link
1111 * SecurityManager#checkRead(String)} method denies read access to
1112 * the directory
1113 */
1114 public String[] list() {
1115 SecurityManager security = System.getSecurityManager();
1116 if (security != null) {
1117 security.checkRead(path);
1118 }
1119 if (isInvalid()) {
1120 return null;
1121 }
1122 return fs.list(this);
1123 }
1124
1125 /**
1126 * Returns an array of strings naming the files and directories in the
1127 * directory denoted by this abstract pathname that satisfy the specified
1128 * filter. The behavior of this method is the same as that of the
1129 * {@link #list()} method, except that the strings in the returned array
1130 * must satisfy the filter. If the given {@code filter} is {@code null}
1131 * then all names are accepted. Otherwise, a name satisfies the filter if
1132 * and only if the value {@code true} results when the {@link
1133 * FilenameFilter#accept FilenameFilter.accept(File, String)} method
1134 * of the filter is invoked on this abstract pathname and the name of a
1135 * file or directory in the directory that it denotes.
1136 *
1137 * @param filter
1138 * A filename filter
1139 *
1140 * @return An array of strings naming the files and directories in the
1141 * directory denoted by this abstract pathname that were accepted
1142 * by the given {@code filter}. The array will be empty if the
1143 * directory is empty or if no names were accepted by the filter.
1144 * Returns {@code null} if this abstract pathname does not denote
1145 * a directory, or if an I/O error occurs.
1146 *
1147 * @throws SecurityException
1148 * If a security manager exists and its {@link
1149 * SecurityManager#checkRead(String)} method denies read access to
1150 * the directory
1151 *
1152 * @see java.nio.file.Files#newDirectoryStream(Path,String)
1153 */
1154 public String[] list(FilenameFilter filter) {
1155 String names[] = list();
1156 if ((names == null) || (filter == null)) {
1157 return names;
1158 }
1159 List<String> v = new ArrayList<>();
1160 for (int i = 0 ; i < names.length ; i++) {
1161 if (filter.accept(this, names[i])) {
1162 v.add(names[i]);
1163 }
1164 }
1165 return v.toArray(new String[v.size()]);
1166 }
1167
1168 /**
1169 * Returns an array of abstract pathnames denoting the files in the
1170 * directory denoted by this abstract pathname.
1171 *
1172 * <p> If this abstract pathname does not denote a directory, then this
1173 * method returns {@code null}. Otherwise an array of {@code File} objects
1174 * is returned, one for each file or directory in the directory. Pathnames
1175 * denoting the directory itself and the directory's parent directory are
1176 * not included in the result. Each resulting abstract pathname is
1177 * constructed from this abstract pathname using the {@link #File(File,
1178 * String) File(File, String)} constructor. Therefore if this
1179 * pathname is absolute then each resulting pathname is absolute; if this
1180 * pathname is relative then each resulting pathname will be relative to
1181 * the same directory.
1182 *
1183 * <p> There is no guarantee that the name strings in the resulting array
1184 * will appear in any specific order; they are not, in particular,
1185 * guaranteed to appear in alphabetical order.
1186 *
1187 * <p> Note that the {@link java.nio.file.Files} class defines the {@link
1188 * java.nio.file.Files#newDirectoryStream(Path) newDirectoryStream} method
1189 * to open a directory and iterate over the names of the files in the
1190 * directory. This may use less resources when working with very large
1191 * directories.
1192 *
1193 * @return An array of abstract pathnames denoting the files and
1194 * directories in the directory denoted by this abstract pathname.
1195 * The array will be empty if the directory is empty. Returns
1196 * {@code null} if this abstract pathname does not denote a
1197 * directory, or if an I/O error occurs.
1198 *
1199 * @throws SecurityException
1200 * If a security manager exists and its {@link
1201 * SecurityManager#checkRead(String)} method denies read access to
1202 * the directory
1203 *
1204 * @since 1.2
1205 */
1206 public File[] listFiles() {
1207 String[] ss = list();
1208 if (ss == null) return null;
1209 int n = ss.length;
1210 File[] fs = new File[n];
1211 for (int i = 0; i < n; i++) {
1212 fs[i] = new File(ss[i], this);
1213 }
1214 return fs;
1215 }
1216
1217 /**
1218 * Returns an array of abstract pathnames denoting the files and
1219 * directories in the directory denoted by this abstract pathname that
1220 * satisfy the specified filter. The behavior of this method is the same
1221 * as that of the {@link #listFiles()} method, except that the pathnames in
1222 * the returned array must satisfy the filter. If the given {@code filter}
1223 * is {@code null} then all pathnames are accepted. Otherwise, a pathname
1224 * satisfies the filter if and only if the value {@code true} results when
1225 * the {@link FilenameFilter#accept
1226 * FilenameFilter.accept(File, String)} method of the filter is
1227 * invoked on this abstract pathname and the name of a file or directory in
1228 * the directory that it denotes.
1229 *
1230 * @param filter
1231 * A filename filter
1232 *
1233 * @return An array of abstract pathnames denoting the files and
1234 * directories in the directory denoted by this abstract pathname.
1235 * The array will be empty if the directory is empty. Returns
1236 * {@code null} if this abstract pathname does not denote a
1237 * directory, or if an I/O error occurs.
1238 *
1239 * @throws SecurityException
1240 * If a security manager exists and its {@link
1241 * SecurityManager#checkRead(String)} method denies read access to
1242 * the directory
1243 *
1244 * @since 1.2
1245 * @see java.nio.file.Files#newDirectoryStream(Path,String)
1246 */
1247 public File[] listFiles(FilenameFilter filter) {
1248 String ss[] = list();
1249 if (ss == null) return null;
1250 ArrayList<File> files = new ArrayList<>();
1251 for (String s : ss)
1252 if ((filter == null) || filter.accept(this, s))
1253 files.add(new File(s, this));
1254 return files.toArray(new File[files.size()]);
1255 }
1256
1257 /**
1258 * Returns an array of abstract pathnames denoting the files and
1259 * directories in the directory denoted by this abstract pathname that
1260 * satisfy the specified filter. The behavior of this method is the same
1261 * as that of the {@link #listFiles()} method, except that the pathnames in
1262 * the returned array must satisfy the filter. If the given {@code filter}
1263 * is {@code null} then all pathnames are accepted. Otherwise, a pathname
1264 * satisfies the filter if and only if the value {@code true} results when
1265 * the {@link FileFilter#accept FileFilter.accept(File)} method of the
1266 * filter is invoked on the pathname.
1267 *
1268 * @param filter
1269 * A file filter
1270 *
1271 * @return An array of abstract pathnames denoting the files and
1272 * directories in the directory denoted by this abstract pathname.
1273 * The array will be empty if the directory is empty. Returns
1274 * {@code null} if this abstract pathname does not denote a
1275 * directory, or if an I/O error occurs.
1276 *
1277 * @throws SecurityException
1278 * If a security manager exists and its {@link
1279 * SecurityManager#checkRead(String)} method denies read access to
1280 * the directory
1281 *
1282 * @since 1.2
1283 * @see java.nio.file.Files#newDirectoryStream(Path,java.nio.file.DirectoryStream.Filter)
1284 */
1285 public File[] listFiles(FileFilter filter) {
1286 String ss[] = list();
1287 if (ss == null) return null;
1288 ArrayList<File> files = new ArrayList<>();
1289 for (String s : ss) {
1290 File f = new File(s, this);
1291 if ((filter == null) || filter.accept(f))
1292 files.add(f);
1293 }
1294 return files.toArray(new File[files.size()]);
1295 }
1296
1297 /**
1298 * Creates the directory named by this abstract pathname.
1299 *
1300 * @return <code>true</code> if and only if the directory was
1301 * created; <code>false</code> otherwise
1302 *
1303 * @throws SecurityException
1304 * If a security manager exists and its <code>{@link
1305 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1306 * method does not permit the named directory to be created
1307 */
1308 public boolean mkdir() {
1309 SecurityManager security = System.getSecurityManager();
1310 if (security != null) {
1311 security.checkWrite(path);
1312 }
1313 if (isInvalid()) {
1314 return false;
1315 }
1316 return fs.createDirectory(this);
1317 }
1318
1319 /**
1320 * Creates the directory named by this abstract pathname, including any
1321 * necessary but nonexistent parent directories. Note that if this
1322 * operation fails it may have succeeded in creating some of the necessary
1323 * parent directories.
1324 *
1325 * @return <code>true</code> if and only if the directory was created,
1326 * along with all necessary parent directories; <code>false</code>
1327 * otherwise
1328 *
1329 * @throws SecurityException
1330 * If a security manager exists and its <code>{@link
1331 * java.lang.SecurityManager#checkRead(java.lang.String)}</code>
1332 * method does not permit verification of the existence of the
1333 * named directory and all necessary parent directories; or if
1334 * the <code>{@link
1335 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1336 * method does not permit the named directory and all necessary
1337 * parent directories to be created
1338 */
1339 public boolean mkdirs() {
1340 if (exists()) {
1341 return false;
1342 }
1343 if (mkdir()) {
1344 return true;
1345 }
1346 File canonFile = null;
1347 try {
1348 canonFile = getCanonicalFile();
1349 } catch (IOException e) {
1350 return false;
1351 }
1352
1353 File parent = canonFile.getParentFile();
1354 return (parent != null && (parent.mkdirs() || parent.exists()) &&
1355 canonFile.mkdir());
1356 }
1357
1358 /**
1359 * Renames the file denoted by this abstract pathname.
1360 *
1361 * <p> Many aspects of the behavior of this method are inherently
1362 * platform-dependent: The rename operation might not be able to move a
1363 * file from one filesystem to another, it might not be atomic, and it
1364 * might not succeed if a file with the destination abstract pathname
1365 * already exists. The return value should always be checked to make sure
1366 * that the rename operation was successful.
1367 *
1368 * <p> Note that the {@link java.nio.file.Files} class defines the {@link
1369 * java.nio.file.Files#move move} method to move or rename a file in a
1370 * platform independent manner.
1371 *
1372 * @param dest The new abstract pathname for the named file
1373 *
1374 * @return <code>true</code> if and only if the renaming succeeded;
1375 * <code>false</code> otherwise
1376 *
1377 * @throws SecurityException
1378 * If a security manager exists and its <code>{@link
1379 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1380 * method denies write access to either the old or new pathnames
1381 *
1382 * @throws NullPointerException
1383 * If parameter <code>dest</code> is <code>null</code>
1384 */
1385 public boolean renameTo(File dest) {
1386 SecurityManager security = System.getSecurityManager();
1387 if (security != null) {
1388 security.checkWrite(path);
1389 security.checkWrite(dest.path);
1390 }
1391 if (dest == null) {
1392 throw new NullPointerException();
1393 }
1394 if (this.isInvalid() || dest.isInvalid()) {
1395 return false;
1396 }
1397 return fs.rename(this, dest);
1398 }
1399
1400 /**
1401 * Sets the last-modified time of the file or directory named by this
1402 * abstract pathname.
1403 *
1404 * <p> All platforms support file-modification times to the nearest second,
1405 * but some provide more precision. The argument will be truncated to fit
1406 * the supported precision. If the operation succeeds and no intervening
1407 * operations on the file take place, then the next invocation of the
1408 * <code>{@link #lastModified}</code> method will return the (possibly
1409 * truncated) <code>time</code> argument that was passed to this method.
1410 *
1411 * @param time The new last-modified time, measured in milliseconds since
1412 * the epoch (00:00:00 GMT, January 1, 1970)
1413 *
1414 * @return <code>true</code> if and only if the operation succeeded;
1415 * <code>false</code> otherwise
1416 *
1417 * @throws IllegalArgumentException If the argument is negative
1418 *
1419 * @throws SecurityException
1420 * If a security manager exists and its <code>{@link
1421 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1422 * method denies write access to the named file
1423 *
1424 * @since 1.2
1425 */
1426 public boolean setLastModified(long time) {
1427 if (time < 0) throw new IllegalArgumentException("Negative time");
1428 SecurityManager security = System.getSecurityManager();
1429 if (security != null) {
1430 security.checkWrite(path);
1431 }
1432 if (isInvalid()) {
1433 return false;
1434 }
1435 return fs.setLastModifiedTime(this, time);
1436 }
1437
1438 /**
1439 * Marks the file or directory named by this abstract pathname so that
1440 * only read operations are allowed. After invoking this method the file
1441 * or directory will not change until it is either deleted or marked
1442 * to allow write access. On some platforms it may be possible to start the
1443 * Java virtual machine with special privileges that allow it to modify
1444 * files that are marked read-only. Whether or not a read-only file or
1445 * directory may be deleted depends upon the underlying system.
1446 *
1447 * @return <code>true</code> if and only if the operation succeeded;
1448 * <code>false</code> otherwise
1449 *
1450 * @throws SecurityException
1451 * If a security manager exists and its <code>{@link
1452 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1453 * method denies write access to the named file
1454 *
1455 * @since 1.2
1456 */
1457 public boolean setReadOnly() {
1458 SecurityManager security = System.getSecurityManager();
1459 if (security != null) {
1460 security.checkWrite(path);
1461 }
1462 if (isInvalid()) {
1463 return false;
1464 }
1465 return fs.setReadOnly(this);
1466 }
1467
1468 /**
1469 * Sets the owner's or everybody's write permission for this abstract
1470 * pathname. On some platforms it may be possible to start the Java virtual
1471 * machine with special privileges that allow it to modify files that
1472 * disallow write operations.
1473 *
1474 * <p> The {@link java.nio.file.Files} class defines methods that operate on
1475 * file attributes including file permissions. This may be used when finer
1476 * manipulation of file permissions is required.
1477 *
1478 * @param writable
1479 * If <code>true</code>, sets the access permission to allow write
1480 * operations; if <code>false</code> to disallow write operations
1481 *
1482 * @param ownerOnly
1483 * If <code>true</code>, the write permission applies only to the
1484 * owner's write permission; otherwise, it applies to everybody. If
1485 * the underlying file system can not distinguish the owner's write
1486 * permission from that of others, then the permission will apply to
1487 * everybody, regardless of this value.
1488 *
1489 * @return <code>true</code> if and only if the operation succeeded. The
1490 * operation will fail if the user does not have permission to change
1491 * the access permissions of this abstract pathname.
1492 *
1493 * @throws SecurityException
1494 * If a security manager exists and its <code>{@link
1495 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1496 * method denies write access to the named file
1497 *
1498 * @since 1.6
1499 */
1500 public boolean setWritable(boolean writable, boolean ownerOnly) {
1501 SecurityManager security = System.getSecurityManager();
1502 if (security != null) {
1503 security.checkWrite(path);
1504 }
1505 if (isInvalid()) {
1506 return false;
1507 }
1508 return fs.setPermission(this, FileSystem.ACCESS_WRITE, writable, ownerOnly);
1509 }
1510
1511 /**
1512 * A convenience method to set the owner's write permission for this abstract
1513 * pathname. On some platforms it may be possible to start the Java virtual
1514 * machine with special privileges that allow it to modify files that
1515 * disallow write operations.
1516 *
1517 * <p> An invocation of this method of the form <tt>file.setWritable(arg)</tt>
1518 * behaves in exactly the same way as the invocation
1519 *
1520 * <pre>
1521 * file.setWritable(arg, true) </pre>
1522 *
1523 * @param writable
1524 * If <code>true</code>, sets the access permission to allow write
1525 * operations; if <code>false</code> to disallow write operations
1526 *
1527 * @return <code>true</code> if and only if the operation succeeded. The
1528 * operation will fail if the user does not have permission to
1529 * change the access permissions of this abstract pathname.
1530 *
1531 * @throws SecurityException
1532 * If a security manager exists and its <code>{@link
1533 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1534 * method denies write access to the file
1535 *
1536 * @since 1.6
1537 */
1538 public boolean setWritable(boolean writable) {
1539 return setWritable(writable, true);
1540 }
1541
1542 /**
1543 * Sets the owner's or everybody's read permission for this abstract
1544 * pathname. On some platforms it may be possible to start the Java virtual
1545 * machine with special privileges that allow it to read files that are
1546 * marked as unreadable.
1547 *
1548 * <p> The {@link java.nio.file.Files} class defines methods that operate on
1549 * file attributes including file permissions. This may be used when finer
1550 * manipulation of file permissions is required.
1551 *
1552 * @param readable
1553 * If <code>true</code>, sets the access permission to allow read
1554 * operations; if <code>false</code> to disallow read operations
1555 *
1556 * @param ownerOnly
1557 * If <code>true</code>, the read permission applies only to the
1558 * owner's read permission; otherwise, it applies to everybody. If
1559 * the underlying file system can not distinguish the owner's read
1560 * permission from that of others, then the permission will apply to
1561 * everybody, regardless of this value.
1562 *
1563 * @return <code>true</code> if and only if the operation succeeded. The
1564 * operation will fail if the user does not have permission to
1565 * change the access permissions of this abstract pathname. If
1566 * <code>readable</code> is <code>false</code> and the underlying
1567 * file system does not implement a read permission, then the
1568 * operation will fail.
1569 *
1570 * @throws SecurityException
1571 * If a security manager exists and its <code>{@link
1572 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1573 * method denies write access to the file
1574 *
1575 * @since 1.6
1576 */
1577 public boolean setReadable(boolean readable, boolean ownerOnly) {
1578 SecurityManager security = System.getSecurityManager();
1579 if (security != null) {
1580 security.checkWrite(path);
1581 }
1582 if (isInvalid()) {
1583 return false;
1584 }
1585 return fs.setPermission(this, FileSystem.ACCESS_READ, readable, ownerOnly);
1586 }
1587
1588 /**
1589 * A convenience method to set the owner's read permission for this abstract
1590 * pathname. On some platforms it may be possible to start the Java virtual
1591 * machine with special privileges that allow it to read files that that are
1592 * marked as unreadable.
1593 *
1594 * <p>An invocation of this method of the form <tt>file.setReadable(arg)</tt>
1595 * behaves in exactly the same way as the invocation
1596 *
1597 * <pre>
1598 * file.setReadable(arg, true) </pre>
1599 *
1600 * @param readable
1601 * If <code>true</code>, sets the access permission to allow read
1602 * operations; if <code>false</code> to disallow read operations
1603 *
1604 * @return <code>true</code> if and only if the operation succeeded. The
1605 * operation will fail if the user does not have permission to
1606 * change the access permissions of this abstract pathname. If
1607 * <code>readable</code> is <code>false</code> and the underlying
1608 * file system does not implement a read permission, then the
1609 * operation will fail.
1610 *
1611 * @throws SecurityException
1612 * If a security manager exists and its <code>{@link
1613 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1614 * method denies write access to the file
1615 *
1616 * @since 1.6
1617 */
1618 public boolean setReadable(boolean readable) {
1619 return setReadable(readable, true);
1620 }
1621
1622 /**
1623 * Sets the owner's or everybody's execute permission for this abstract
1624 * pathname. On some platforms it may be possible to start the Java virtual
1625 * machine with special privileges that allow it to execute files that are
1626 * not marked executable.
1627 *
1628 * <p> The {@link java.nio.file.Files} class defines methods that operate on
1629 * file attributes including file permissions. This may be used when finer
1630 * manipulation of file permissions is required.
1631 *
1632 * @param executable
1633 * If <code>true</code>, sets the access permission to allow execute
1634 * operations; if <code>false</code> to disallow execute operations
1635 *
1636 * @param ownerOnly
1637 * If <code>true</code>, the execute permission applies only to the
1638 * owner's execute permission; otherwise, it applies to everybody.
1639 * If the underlying file system can not distinguish the owner's
1640 * execute permission from that of others, then the permission will
1641 * apply to everybody, regardless of this value.
1642 *
1643 * @return <code>true</code> if and only if the operation succeeded. The
1644 * operation will fail if the user does not have permission to
1645 * change the access permissions of this abstract pathname. If
1646 * <code>executable</code> is <code>false</code> and the underlying
1647 * file system does not implement an execute permission, then the
1648 * operation will fail.
1649 *
1650 * @throws SecurityException
1651 * If a security manager exists and its <code>{@link
1652 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1653 * method denies write access to the file
1654 *
1655 * @since 1.6
1656 */
1657 public boolean setExecutable(boolean executable, boolean ownerOnly) {
1658 SecurityManager security = System.getSecurityManager();
1659 if (security != null) {
1660 security.checkWrite(path);
1661 }
1662 if (isInvalid()) {
1663 return false;
1664 }
1665 return fs.setPermission(this, FileSystem.ACCESS_EXECUTE, executable, ownerOnly);
1666 }
1667
1668 /**
1669 * A convenience method to set the owner's execute permission for this
1670 * abstract pathname. On some platforms it may be possible to start the Java
1671 * virtual machine with special privileges that allow it to execute files
1672 * that are not marked executable.
1673 *
1674 * <p>An invocation of this method of the form <tt>file.setExcutable(arg)</tt>
1675 * behaves in exactly the same way as the invocation
1676 *
1677 * <pre>
1678 * file.setExecutable(arg, true) </pre>
1679 *
1680 * @param executable
1681 * If <code>true</code>, sets the access permission to allow execute
1682 * operations; if <code>false</code> to disallow execute operations
1683 *
1684 * @return <code>true</code> if and only if the operation succeeded. The
1685 * operation will fail if the user does not have permission to
1686 * change the access permissions of this abstract pathname. If
1687 * <code>executable</code> is <code>false</code> and the underlying
1688 * file system does not implement an excute permission, then the
1689 * operation will fail.
1690 *
1691 * @throws SecurityException
1692 * If a security manager exists and its <code>{@link
1693 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1694 * method denies write access to the file
1695 *
1696 * @since 1.6
1697 */
1698 public boolean setExecutable(boolean executable) {
1699 return setExecutable(executable, true);
1700 }
1701
1702 /**
1703 * Tests whether the application can execute the file denoted by this
1704 * abstract pathname. On some platforms it may be possible to start the
1705 * Java virtual machine with special privileges that allow it to execute
1706 * files that are not marked executable. Consequently this method may return
1707 * {@code true} even though the file does not have execute permissions.
1708 *
1709 * @return <code>true</code> if and only if the abstract pathname exists
1710 * <em>and</em> the application is allowed to execute the file
1711 *
1712 * @throws SecurityException
1713 * If a security manager exists and its <code>{@link
1714 * java.lang.SecurityManager#checkExec(java.lang.String)}</code>
1715 * method denies execute access to the file
1716 *
1717 * @since 1.6
1718 */
1719 public boolean canExecute() {
1720 SecurityManager security = System.getSecurityManager();
1721 if (security != null) {
1722 security.checkExec(path);
1723 }
1724 if (isInvalid()) {
1725 return false;
1726 }
1727 return fs.checkAccess(this, FileSystem.ACCESS_EXECUTE);
1728 }
1729
1730
1731 /* -- Filesystem interface -- */
1732
1733 /**
1734 * List the available filesystem roots.
1735 *
1736 * <p> A particular Java platform may support zero or more
1737 * hierarchically-organized file systems. Each file system has a
1738 * {@code root} directory from which all other files in that file system
1739 * can be reached. Windows platforms, for example, have a root directory
1740 * for each active drive; UNIX platforms have a single root directory,
1741 * namely {@code "/"}. The set of available filesystem roots is affected
1742 * by various system-level operations such as the insertion or ejection of
1743 * removable media and the disconnecting or unmounting of physical or
1744 * virtual disk drives.
1745 *
1746 * <p> This method returns an array of {@code File} objects that denote the
1747 * root directories of the available filesystem roots. It is guaranteed
1748 * that the canonical pathname of any file physically present on the local
1749 * machine will begin with one of the roots returned by this method.
1750 *
1751 * <p> The canonical pathname of a file that resides on some other machine
1752 * and is accessed via a remote-filesystem protocol such as SMB or NFS may
1753 * or may not begin with one of the roots returned by this method. If the
1754 * pathname of a remote file is syntactically indistinguishable from the
1755 * pathname of a local file then it will begin with one of the roots
1756 * returned by this method. Thus, for example, {@code File} objects
1757 * denoting the root directories of the mapped network drives of a Windows
1758 * platform will be returned by this method, while {@code File} objects
1759 * containing UNC pathnames will not be returned by this method.
1760 *
1761 * <p> Unlike most methods in this class, this method does not throw
1762 * security exceptions. If a security manager exists and its {@link
1763 * SecurityManager#checkRead(String)} method denies read access to a
1764 * particular root directory, then that directory will not appear in the
1765 * result.
1766 *
1767 * @return An array of {@code File} objects denoting the available
1768 * filesystem roots, or {@code null} if the set of roots could not
1769 * be determined. The array will be empty if there are no
1770 * filesystem roots.
1771 *
1772 * @since 1.2
1773 * @see java.nio.file.FileStore
1774 */
1775 public static File[] listRoots() {
1776 return fs.listRoots();
1777 }
1778
1779
1780 /* -- Disk usage -- */
1781
1782 /**
1783 * Returns the size of the partition <a href="#partName">named</a> by this
1784 * abstract pathname.
1785 *
1786 * @return The size, in bytes, of the partition or <tt>0L</tt> if this
1787 * abstract pathname does not name a partition
1788 *
1789 * @throws SecurityException
1790 * If a security manager has been installed and it denies
1791 * {@link RuntimePermission}<tt>("getFileSystemAttributes")</tt>
1792 * or its {@link SecurityManager#checkRead(String)} method denies
1793 * read access to the file named by this abstract pathname
1794 *
1795 * @since 1.6
1796 */
1797 public long getTotalSpace() {
1798 SecurityManager sm = System.getSecurityManager();
1799 if (sm != null) {
1800 sm.checkPermission(new RuntimePermission("getFileSystemAttributes"));
1801 sm.checkRead(path);
1802 }
1803 if (isInvalid()) {
1804 return 0L;
1805 }
1806 return fs.getSpace(this, FileSystem.SPACE_TOTAL);
1807 }
1808
1809 /**
1810 * Returns the number of unallocated bytes in the partition <a
1811 * href="#partName">named</a> by this abstract path name.
1812 *
1813 * <p> The returned number of unallocated bytes is a hint, but not
1814 * a guarantee, that it is possible to use most or any of these
1815 * bytes. The number of unallocated bytes is most likely to be
1816 * accurate immediately after this call. It is likely to be made
1817 * inaccurate by any external I/O operations including those made
1818 * on the system outside of this virtual machine. This method
1819 * makes no guarantee that write operations to this file system
1820 * will succeed.
1821 *
1822 * @return The number of unallocated bytes on the partition or <tt>0L</tt>
1823 * if the abstract pathname does not name a partition. This
1824 * value will be less than or equal to the total file system size
1825 * returned by {@link #getTotalSpace}.
1826 *
1827 * @throws SecurityException
1828 * If a security manager has been installed and it denies
1829 * {@link RuntimePermission}<tt>("getFileSystemAttributes")</tt>
1830 * or its {@link SecurityManager#checkRead(String)} method denies
1831 * read access to the file named by this abstract pathname
1832 *
1833 * @since 1.6
1834 */
1835 public long getFreeSpace() {
1836 SecurityManager sm = System.getSecurityManager();
1837 if (sm != null) {
1838 sm.checkPermission(new RuntimePermission("getFileSystemAttributes"));
1839 sm.checkRead(path);
1840 }
1841 if (isInvalid()) {
1842 return 0L;
1843 }
1844 return fs.getSpace(this, FileSystem.SPACE_FREE);
1845 }
1846
1847 /**
1848 * Returns the number of bytes available to this virtual machine on the
1849 * partition <a href="#partName">named</a> by this abstract pathname. When
1850 * possible, this method checks for write permissions and other operating
1851 * system restrictions and will therefore usually provide a more accurate
1852 * estimate of how much new data can actually be written than {@link
1853 * #getFreeSpace}.
1854 *
1855 * <p> The returned number of available bytes is a hint, but not a
1856 * guarantee, that it is possible to use most or any of these bytes. The
1857 * number of unallocated bytes is most likely to be accurate immediately
1858 * after this call. It is likely to be made inaccurate by any external
1859 * I/O operations including those made on the system outside of this
1860 * virtual machine. This method makes no guarantee that write operations
1861 * to this file system will succeed.
1862 *
1863 * @return The number of available bytes on the partition or <tt>0L</tt>
1864 * if the abstract pathname does not name a partition. On
1865 * systems where this information is not available, this method
1866 * will be equivalent to a call to {@link #getFreeSpace}.
1867 *
1868 * @throws SecurityException
1869 * If a security manager has been installed and it denies
1870 * {@link RuntimePermission}<tt>("getFileSystemAttributes")</tt>
1871 * or its {@link SecurityManager#checkRead(String)} method denies
1872 * read access to the file named by this abstract pathname
1873 *
1874 * @since 1.6
1875 */
1876 public long getUsableSpace() {
1877 SecurityManager sm = System.getSecurityManager();
1878 if (sm != null) {
1879 sm.checkPermission(new RuntimePermission("getFileSystemAttributes"));
1880 sm.checkRead(path);
1881 }
1882 if (isInvalid()) {
1883 return 0L;
1884 }
1885 return fs.getSpace(this, FileSystem.SPACE_USABLE);
1886 }
1887
1888 /* -- Temporary files -- */
1889
1890 private static class TempDirectory {
1891 private TempDirectory() { }
1892
1893 // temporary directory location
1894 private static final File tmpdir = new File(AccessController
1895 .doPrivileged(new GetPropertyAction("java.io.tmpdir")));
1896 static File location() {
1897 return tmpdir;
1898 }
1899
1900 // file name generation
1901 private static final SecureRandom random = new SecureRandom();
1902 static File generateFile(String prefix, String suffix, File dir)
1903 throws IOException
1904 {
1905 long n = random.nextLong();
1906 if (n == Long.MIN_VALUE) {
1907 n = 0; // corner case
1908 } else {
1909 n = Math.abs(n);
1910 }
1911 String name = prefix + Long.toString(n) + suffix;
1912 File f = new File(dir, name);
1913 if (!name.equals(f.getName()))
1914 throw new IOException("Unable to create temporary file");
1915 return f;
1916 }
1917 }
1918
1919 /**
1920 * <p> Creates a new empty file in the specified directory, using the
1921 * given prefix and suffix strings to generate its name. If this method
1922 * returns successfully then it is guaranteed that:
1923 *
1924 * <ol>
1925 * <li> The file denoted by the returned abstract pathname did not exist
1926 * before this method was invoked, and
1927 * <li> Neither this method nor any of its variants will return the same
1928 * abstract pathname again in the current invocation of the virtual
1929 * machine.
1930 * </ol>
1931 *
1932 * This method provides only part of a temporary-file facility. To arrange
1933 * for a file created by this method to be deleted automatically, use the
1934 * <code>{@link #deleteOnExit}</code> method.
1935 *
1936 * <p> The <code>prefix</code> argument must be at least three characters
1937 * long. It is recommended that the prefix be a short, meaningful string
1938 * such as <code>"hjb"</code> or <code>"mail"</code>. The
1939 * <code>suffix</code> argument may be <code>null</code>, in which case the
1940 * suffix <code>".tmp"</code> will be used.
1941 *
1942 * <p> To create the new file, the prefix and the suffix may first be
1943 * adjusted to fit the limitations of the underlying platform. If the
1944 * prefix is too long then it will be truncated, but its first three
1945 * characters will always be preserved. If the suffix is too long then it
1946 * too will be truncated, but if it begins with a period character
1947 * (<code>'.'</code>) then the period and the first three characters
1948 * following it will always be preserved. Once these adjustments have been
1949 * made the name of the new file will be generated by concatenating the
1950 * prefix, five or more internally-generated characters, and the suffix.
1951 *
1952 * <p> If the <code>directory</code> argument is <code>null</code> then the
1953 * system-dependent default temporary-file directory will be used. The
1954 * default temporary-file directory is specified by the system property
1955 * <code>java.io.tmpdir</code>. On UNIX systems the default value of this
1956 * property is typically <code>"/tmp"</code> or <code>"/var/tmp"</code>; on
1957 * Microsoft Windows systems it is typically <code>"C:\\WINNT\\TEMP"</code>. A different
1958 * value may be given to this system property when the Java virtual machine
1959 * is invoked, but programmatic changes to this property are not guaranteed
1960 * to have any effect upon the temporary directory used by this method.
1961 *
1962 * @param prefix The prefix string to be used in generating the file's
1963 * name; must be at least three characters long
1964 *
1965 * @param suffix The suffix string to be used in generating the file's
1966 * name; may be <code>null</code>, in which case the
1967 * suffix <code>".tmp"</code> will be used
1968 *
1969 * @param directory The directory in which the file is to be created, or
1970 * <code>null</code> if the default temporary-file
1971 * directory is to be used
1972 *
1973 * @return An abstract pathname denoting a newly-created empty file
1974 *
1975 * @throws IllegalArgumentException
1976 * If the <code>prefix</code> argument contains fewer than three
1977 * characters
1978 *
1979 * @throws IOException If a file could not be created
1980 *
1981 * @throws SecurityException
1982 * If a security manager exists and its <code>{@link
1983 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
1984 * method does not allow a file to be created
1985 *
1986 * @since 1.2
1987 */
1988 public static File createTempFile(String prefix, String suffix,
1989 File directory)
1990 throws IOException
1991 {
1992 if (prefix.length() < 3)
1993 throw new IllegalArgumentException("Prefix string too short");
1994 if (suffix == null)
1995 suffix = ".tmp";
1996
1997 File tmpdir = (directory != null) ? directory
1998 : TempDirectory.location();
1999 File f;
2000 try {
2001 do {
2002 f = TempDirectory.generateFile(prefix, suffix, tmpdir);
2003 } while (f.exists());
2004 if (!f.createNewFile())
2005 throw new IOException("Unable to create temporary file");
2006 } catch (SecurityException se) {
2007 // don't reveal temporary directory location
2008 if (directory == null)
2009 throw new SecurityException("Unable to create temporary file");
2010 throw se;
2011 }
2012 return f;
2013 }
2014
2015 /**
2016 * Creates an empty file in the default temporary-file directory, using
2017 * the given prefix and suffix to generate its name. Invoking this method
2018 * is equivalent to invoking <code>{@link #createTempFile(java.lang.String,
2019 * java.lang.String, java.io.File)
2020 * createTempFile(prefix, suffix, null)}</code>.
2021 *
2022 * <p> The {@link
2023 * java.nio.file.Files#createTempFile(String,String,java.nio.file.attribute.FileAttribute[])
2024 * Files.createTempFile} method provides an alternative method to create an
2025 * empty file in the temporary-file directory. Files created by that method
2026 * may have more restrictive access permissions to files created by this
2027 * method and so may be more suited to security-sensitive applications.
2028 *
2029 * @param prefix The prefix string to be used in generating the file's
2030 * name; must be at least three characters long
2031 *
2032 * @param suffix The suffix string to be used in generating the file's
2033 * name; may be <code>null</code>, in which case the
2034 * suffix <code>".tmp"</code> will be used
2035 *
2036 * @return An abstract pathname denoting a newly-created empty file
2037 *
2038 * @throws IllegalArgumentException
2039 * If the <code>prefix</code> argument contains fewer than three
2040 * characters
2041 *
2042 * @throws IOException If a file could not be created
2043 *
2044 * @throws SecurityException
2045 * If a security manager exists and its <code>{@link
2046 * java.lang.SecurityManager#checkWrite(java.lang.String)}</code>
2047 * method does not allow a file to be created
2048 *
2049 * @since 1.2
2050 * @see java.nio.file.Files#createTempDirectory(String,FileAttribute[])
2051 */
2052 public static File createTempFile(String prefix, String suffix)
2053 throws IOException
2054 {
2055 return createTempFile(prefix, suffix, null);
2056 }
2057
2058 /* -- Basic infrastructure -- */
2059
2060 /**
2061 * Compares two abstract pathnames lexicographically. The ordering
2062 * defined by this method depends upon the underlying system. On UNIX
2063 * systems, alphabetic case is significant in comparing pathnames; on Microsoft Windows
2064 * systems it is not.
2065 *
2066 * @param pathname The abstract pathname to be compared to this abstract
2067 * pathname
2068 *
2069 * @return Zero if the argument is equal to this abstract pathname, a
2070 * value less than zero if this abstract pathname is
2071 * lexicographically less than the argument, or a value greater
2072 * than zero if this abstract pathname is lexicographically
2073 * greater than the argument
2074 *
2075 * @since 1.2
2076 */
2077 public int compareTo(File pathname) {
2078 return fs.compare(this, pathname);
2079 }
2080
2081 /**
2082 * Tests this abstract pathname for equality with the given object.
2083 * Returns <code>true</code> if and only if the argument is not
2084 * <code>null</code> and is an abstract pathname that denotes the same file
2085 * or directory as this abstract pathname. Whether or not two abstract
2086 * pathnames are equal depends upon the underlying system. On UNIX
2087 * systems, alphabetic case is significant in comparing pathnames; on Microsoft Windows
2088 * systems it is not.
2089 *
2090 * @param obj The object to be compared with this abstract pathname
2091 *
2092 * @return <code>true</code> if and only if the objects are the same;
2093 * <code>false</code> otherwise
2094 */
2095 public boolean equals(Object obj) {
2096 if ((obj != null) && (obj instanceof File)) {
2097 return compareTo((File)obj) == 0;
2098 }
2099 return false;
2100 }
2101
2102 /**
2103 * Computes a hash code for this abstract pathname. Because equality of
2104 * abstract pathnames is inherently system-dependent, so is the computation
2105 * of their hash codes. On UNIX systems, the hash code of an abstract
2106 * pathname is equal to the exclusive <em>or</em> of the hash code
2107 * of its pathname string and the decimal value
2108 * <code>1234321</code>. On Microsoft Windows systems, the hash
2109 * code is equal to the exclusive <em>or</em> of the hash code of
2110 * its pathname string converted to lower case and the decimal
2111 * value <code>1234321</code>. Locale is not taken into account on
2112 * lowercasing the pathname string.
2113 *
2114 * @return A hash code for this abstract pathname
2115 */
2116 public int hashCode() {
2117 return fs.hashCode(this);
2118 }
2119
2120 /**
2121 * Returns the pathname string of this abstract pathname. This is just the
2122 * string returned by the <code>{@link #getPath}</code> method.
2123 *
2124 * @return The string form of this abstract pathname
2125 */
2126 public String toString() {
2127 return getPath();
2128 }
2129
2130 /**
2131 * WriteObject is called to save this filename.
2132 * The separator character is saved also so it can be replaced
2133 * in case the path is reconstituted on a different host type.
2134 * <p>
2135 * @serialData Default fields followed by separator character.
2136 */
2137 private synchronized void writeObject(java.io.ObjectOutputStream s)
2138 throws IOException
2139 {
2140 s.defaultWriteObject();
2141 s.writeChar(separatorChar); // Add the separator character
2142 }
2143
2144 /**
2145 * readObject is called to restore this filename.
2146 * The original separator character is read. If it is different
2147 * than the separator character on this system, then the old separator
2148 * is replaced by the local separator.
2149 */
2150 private synchronized void readObject(java.io.ObjectInputStream s)
2151 throws IOException, ClassNotFoundException
2152 {
2153 ObjectInputStream.GetField fields = s.readFields();
2154 String pathField = (String)fields.get("path", null);
2155 char sep = s.readChar(); // read the previous separator char
2156 if (sep != separatorChar)
2157 pathField = pathField.replace(sep, separatorChar);
2158 String path = fs.normalize(pathField);
2159 UNSAFE.putObject(this, PATH_OFFSET, path);
2160 UNSAFE.putIntVolatile(this, PREFIX_LENGTH_OFFSET, fs.prefixLength(path));
2161 }
2162
2163 private static final long PATH_OFFSET;
2164 private static final long PREFIX_LENGTH_OFFSET;
2165 private static final sun.misc.Unsafe UNSAFE;
2166 static {
2167 try {
2168 sun.misc.Unsafe unsafe = sun.misc.Unsafe.getUnsafe();
2169 PATH_OFFSET = unsafe.objectFieldOffset(
2170 File.class.getDeclaredField("path"));
2171 PREFIX_LENGTH_OFFSET = unsafe.objectFieldOffset(
2172 File.class.getDeclaredField("prefixLength"));
2173 UNSAFE = unsafe;
2174 } catch (ReflectiveOperationException e) {
2175 throw new Error(e);
2176 }
2177 }
2178
2179
2180 /** use serialVersionUID from JDK 1.0.2 for interoperability */
2181 private static final long serialVersionUID = 301077366599181567L;
2182
2183 // -- Integration with java.nio.file --
2184
2185 private volatile transient Path filePath;
2186
2187 /**
2188 * Returns a {@link Path java.nio.file.Path} object constructed from the
2189 * this abstract path. The resulting {@code Path} is associated with the
2190 * {@link java.nio.file.FileSystems#getDefault default-filesystem}.
2191 *
2192 * <p> The first invocation of this method works as if invoking it were
2193 * equivalent to evaluating the expression:
2194 * <blockquote><pre>
2195 * {@link java.nio.file.FileSystems#getDefault FileSystems.getDefault}().{@link
2196 * java.nio.file.FileSystem#getPath getPath}(this.{@link #getPath getPath}());
2197 * </pre></blockquote>
2198 * Subsequent invocations of this method return the same {@code Path}.
2199 *
2200 * <p> If this abstract pathname is the empty abstract pathname then this
2201 * method returns a {@code Path} that may be used to access the current
2202 * user directory.
2203 *
2204 * @return a {@code Path} constructed from this abstract path
2205 *
2206 * @throws java.nio.file.InvalidPathException
2207 * if a {@code Path} object cannot be constructed from the abstract
2208 * path (see {@link java.nio.file.FileSystem#getPath FileSystem.getPath})
2209 *
2210 * @since 1.7
2211 * @see Path#toFile
2212 */
2213 public Path toPath() {
2214 Path result = filePath;
2215 if (result == null) {
2216 synchronized (this) {
2217 result = filePath;
2218 if (result == null) {
2219 result = FileSystems.getDefault().getPath(path);
2220 filePath = result;
2221 }
2222 }
2223 }
2224 return result;
2225 }
2226 }