JavaTM Platform
Standard Ed. 6

java.io
类 File

java.lang.Object
  继承者 java.io.File
所有已实现的接口:
Serializable, Comparable<File>

public class File
extends Object
implements Serializable, Comparable<File>

文件和目录路径名的抽象表示形式。

用户界面和操作系统使用与系统相关的路径名字符串 来命名文件和目录。此类呈现分层路径名的一个抽象的、与系统无关的视图。抽象路径名 有两个组件:

  1. 一个可选的与系统有关的前缀 字符串,比如盘符,"/" 表示 UNIX 中的根目录,"\\\\" 表示 Microsoft Windows UNC 路径名。
  2. 零个或更多字符串名称 的序列。
抽象路径名中的第一个名称是目录名,对于 Microsoft Windows UNC 路径名则是主机名。抽象路径名中第一个名称之后的每个名称表示一个目录;最后一个名称既可以表示目录,也可以表示文件。 抽象路径名没有前缀和名称序列。

路径名字符串与抽象路径名之间的转换与系统有关。将抽象路径名转换为路径名字符串时,每个名称与下一个名称之间用一个默认分隔符 隔开。默认名称分隔符由系统属性 file.separator 定义,可通过此类的公共静态字段 separatorseparatorChar 使其可用。将路径名字符串转换为抽象路径名时,可以使用默认名称分隔符或者底层系统支持的任何其他名称分隔符来分隔其中的名称。

无论是抽象路径名还是路径名字符串,都可以是绝对 路径名或相对 路径名。绝对路径名是完整的路径名,不需要任何其他信息就可以定位它所表示的文件。相反,相对路径名必须使用取自其他路径名的信息进行解释。默认情况下,java.io 包中的类总是根据当前用户目录来解析相对路径名。此目录由系统属性 user.dir 指定,通常是 Java 虚拟机的调用目录。

调用此类的 getParent() 方法可以获取抽象路径名的 路径名,它由路径名前缀以及路径名名称序列中的每个名称(最后一个除外)组成。对于任何具有绝对抽象路径名的 File 对象,如果其绝对抽象路径名以某个目录的绝对路径名开头,那么该目录的绝对路径名是该 File 对象的祖先。例如,抽象路径名 "/usr" 表示的目录是路径名 "/usr/local/bin" 所表示目录的一个祖先。

在处理 UNIX 平台的根目录,以及 Microsoft Windows 平台的盘符、根目录和 UNC 路径名时,将用到前缀这一概念。如下所示:

此类的实例可能表示(也可能不表示)实际文件系统对象,如文件或目录。如果它表示这种对象,那么该对象驻留在一个分区 中。分区是文件系统特定于操作系统的存储分区。一个存储设备(例如,物理磁盘驱动器、闪存、CD-ROM)可以包含多个分区。对象(如果有)将驻留在此路径名(绝对形式)某个祖先指定的分区上。

文件系统可以实现对实际文件系统对象上的某些操作(比如,读、写、执行)进行限制。这些限制统称为访问权限。文件系统可以对一个对象设置多个访问权限。例如,一个设置可能适用于对象的所有者,另一个设置则可能适用于所有其他用户。对象上的访问权限可能导致此类的某些方法执行失败。

File 类的实例是不可变的;也就是说,一旦创建,File 对象表示的抽象路径名将永不改变。

从以下版本开始:
JDK1.0
另请参见:
序列化表格

字段摘要
static String pathSeparator
          与系统有关的路径分隔符,为了方便,它被表示为一个字符串。
static char pathSeparatorChar
          与系统有关的路径分隔符。
static String separator
          与系统有关的默认名称分隔符,为了方便,它被表示为一个字符串。
static char separatorChar
          与系统有关的默认名称分隔符。
 
构造方法摘要
File(File parent, String child)
          根据 parent 抽象路径名和 child 路径名字符串创建一个新 File 实例。
File(String pathname)
          通过将给定路径名字符串转换为抽象路径名来创建一个新 File 实例。
File(String parent, String child)
          根据 parent 路径名字符串和 child 路径名字符串创建一个新 File 实例。
File(URI uri)
          通过将给定的 file: URI 转换为一个抽象路径名来创建一个新的 File 实例。
 
方法摘要
 boolean canExecute()
          测试应用程序是否可以执行此抽象路径名表示的文件。
 boolean canRead()
          测试应用程序是否可以读取此抽象路径名表示的文件。
 boolean canWrite()
          测试应用程序是否可以修改此抽象路径名表示的文件。
 int compareTo(File pathname)
          按字母顺序比较两个抽象路径名。
 boolean createNewFile()
          当且仅当不存在具有此抽象路径名指定名称的文件时,不可分地创建一个新的空文件。
static File createTempFile(String prefix, String suffix)
          在默认临时文件目录中创建一个空文件,使用给定前缀和后缀生成其名称。
static File createTempFile(String prefix, String suffix, File directory)
           在指定目录中创建一个新的空文件,使用给定的前缀和后缀字符串生成其名称。
 boolean delete()
          删除此抽象路径名表示的文件或目录。
 void deleteOnExit()
          在虚拟机终止时,请求删除此抽象路径名表示的文件或目录。
 boolean equals(Object obj)
          测试此抽象路径名与给定对象是否相等。
 boolean exists()
          测试此抽象路径名表示的文件或目录是否存在。
 File getAbsoluteFile()
          返回此抽象路径名的绝对路径名形式。
 String getAbsolutePath()
          返回此抽象路径名的绝对路径名字符串。
 File getCanonicalFile()
          返回此抽象路径名的规范形式。
 String getCanonicalPath()
          返回此抽象路径名的规范路径名字符串。
 long getFreeSpace()
          返回此抽象路径名指定的分区中未分配的字节数。
 String getName()
          返回由此抽象路径名表示的文件或目录的名称。
 String getParent()
          返回此抽象路径名父目录的路径名字符串;如果此路径名没有指定父目录,则返回 null
 File getParentFile()
          返回此抽象路径名父目录的抽象路径名;如果此路径名没有指定父目录,则返回 null
 String getPath()
          将此抽象路径名转换为一个路径名字符串。
 long getTotalSpace()
          返回此抽象路径名指定的分区大小。
 long getUsableSpace()
          返回此抽象路径名指定的分区上可用于此虚拟机的字节数。
 int hashCode()
          计算此抽象路径名的哈希码。
 boolean isAbsolute()
          测试此抽象路径名是否为绝对路径名。
 boolean isDirectory()
          测试此抽象路径名表示的文件是否是一个目录。
 boolean isFile()
          测试此抽象路径名表示的文件是否是一个标准文件。
 boolean isHidden()
          测试此抽象路径名指定的文件是否是一个隐藏文件。
 long lastModified()
          返回此抽象路径名表示的文件最后一次被修改的时间。
 long length()
          返回由此抽象路径名表示的文件的长度。
 String[] list()
          返回一个字符串数组,这些字符串指定此抽象路径名表示的目录中的文件和目录。
 String[] list(FilenameFilter filter)
          返回一个字符串数组,这些字符串指定此抽象路径名表示的目录中满足指定过滤器的文件和目录。
 File[] listFiles()
          返回一个抽象路径名数组,这些路径名表示此抽象路径名表示的目录中的文件。
 File[] listFiles(FileFilter filter)
          返回抽象路径名数组,这些路径名表示此抽象路径名表示的目录中满足指定过滤器的文件和目录。
 File[] listFiles(FilenameFilter filter)
          返回抽象路径名数组,这些路径名表示此抽象路径名表示的目录中满足指定过滤器的文件和目录。
static File[] listRoots()
          列出可用的文件系统根。
 boolean mkdir()
          创建此抽象路径名指定的目录。
 boolean mkdirs()
          创建此抽象路径名指定的目录,包括所有必需但不存在的父目录。
 boolean renameTo(File dest)
          重新命名此抽象路径名表示的文件。
 boolean setExecutable(boolean executable)
          设置此抽象路径名所有者执行权限的一个便捷方法。
 boolean setExecutable(boolean executable, boolean ownerOnly)
          设置此抽象路径名的所有者或所有用户的执行权限。
 boolean setLastModified(long time)
          设置此抽象路径名指定的文件或目录的最后一次修改时间。
 boolean setReadable(boolean readable)
          设置此抽象路径名所有者读权限的一个便捷方法。
 boolean setReadable(boolean readable, boolean ownerOnly)
          设置此抽象路径名的所有者或所有用户的读权限。
 boolean setReadOnly()
          标记此抽象路径名指定的文件或目录,从而只能对其进行读操作。
 boolean setWritable(boolean writable)
          设置此抽象路径名所有者写权限的一个便捷方法。
 boolean setWritable(boolean writable, boolean ownerOnly)
          设置此抽象路径名的所有者或所有用户的写权限。
 String toString()
          返回此抽象路径名的路径名字符串。
 URI toURI()
          构造一个表示此抽象路径名的 file: URI。
 URL toURL()
          已过时。 此方法不会自动转义 URL 中的非法字符。建议新的代码使用以下方式将抽象路径名转换为 URL:首先通过 toURI 方法将其转换为 URI,然后通过 URI.toURL 方法将 URI 装换为 URL。
 
从类 java.lang.Object 继承的方法
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

字段详细信息

separatorChar

public static final char separatorChar
与系统有关的默认名称分隔符。此字段被初始化为包含系统属性 file.separator 值的第一个字符。在 UNIX 系统上,此字段的值为 '/';在 Microsoft Windows 系统上,它为 '\\'

另请参见:
System.getProperty(java.lang.String)

separator

public static final String separator
与系统有关的默认名称分隔符,为了方便,它被表示为一个字符串。此字符串只包含一个字符,即 separatorChar


pathSeparatorChar

public static final char pathSeparatorChar
与系统有关的路径分隔符。此字段被初始为包含系统属性 path.separator 值的第一个字符。此字符用于分隔以路径列表 形式给定的文件序列中的文件名。在 UNIX 系统上,此字段为 ':';在 Microsoft Windows 系统上,它为 ';'

另请参见:
System.getProperty(java.lang.String)

pathSeparator

public static final String pathSeparator
与系统有关的路径分隔符,为了方便,它被表示为一个字符串。此字符串只包含一个字符,即 pathSeparatorChar

构造方法详细信息

File

public File(String pathname)
通过将给定路径名字符串转换为抽象路径名来创建一个新 File 实例。如果给定字符串是空字符串,那么结果是空抽象路径名。

参数:
pathname - 路径名字符串
抛出:
NullPointerException - 如果 pathname 参数为 null

File

public File(String parent,
            String child)
根据 parent 路径名字符串和 child 路径名字符串创建一个新 File 实例。

如果 parentnull,则创建一个新的 File 实例,这与调用以给定 child 路径名字符串作为参数的单参数 File 构造方法效果一样。

否则,parent 路径名字符串用于表示目录,child 路径名字符串用于表示目录或文件。如果 child 路径名字符串是绝对路径名,则用与系统有关的方式将它转换为一个相对路径名。如果 parent 是空字符串,则通过将 child 转换为抽象路径名,并根据与系统有关的默认目录解析结果来创建新的 File 实例。否则,将每个路径名字符串转换为一个抽象路径名,并根据父抽象路径名解析子抽象路径名。

参数:
parent - 父路径名字符串
child - 子路径名字符串
抛出:
NullPointerException - 如果 childnull

File

public File(File parent,
            String child)
根据 parent 抽象路径名和 child 路径名字符串创建一个新 File 实例。

如果 parentnull,则创建一个新的 File 实例,这与调用给定 child 路径名字符串的单参数 File 构造方法的效果一样。

否则,parent 抽象路径名用于表示目录,child 路径名字符串用于表示目录或文件。如果 child 路径名字符串是绝对路径名,则用与系统有关的方式将它转换为一个相对路径名。如果 parent 是空抽象路径名,则通过将 child 转换为抽象路径名,并根据与系统有关的默认目录解析结果来创建新的 File 实例。否则,将每个路径名字符串转换为一个抽象路径名,并根据父抽象路径名解析子抽象路径名。

参数:
parent - 父抽象路径名
child - 子路径名字符串
抛出:
NullPointerException - 如果 childnull

File

public File(URI uri)
通过将给定的 file: URI 转换为一个抽象路径名来创建一个新的 File 实例。

file: URI 的具体形式与系统有关,因此,由此构造方法执行的转换也与系统有关。

对于某个给定抽象路径名 f,可以保证:

new File( f.toURI()).equals( f.getAbsoluteFile())
只要原始抽象路径名、URI 和新抽象路径名都是在同一 Java 虚拟机(或者它的不同调用)中创建的。但是,当在某一操作系统上的虚拟机中创建的 file: URI 在不同操作系统上的虚拟机中被转换为抽象路径名时,这种关系通常是不成立的。

参数:
uri - 一个绝对分层 URI,由一个等于 "file" 的 scheme、非空的 path 组件,以及未定义的 authority、query 和 fragment 组件组成
抛出:
NullPointerException - 如果 urinull
IllegalArgumentException - 如果关于参数的前提不成立
从以下版本开始:
1.4
另请参见:
toURI(), URI
方法详细信息

getName

public String getName()
返回由此抽象路径名表示的文件或目录的名称。该名称是路径名名称序列中的最后一个名称。如果路径名名称序列为空,则返回空字符串。

返回:
此抽象路径名表示的文件或目录的名称;如果路径名的名称序列为空,则返回空字符串

getParent

public String getParent()
返回此抽象路径名父目录的路径名字符串;如果此路径名没有指定父目录,则返回 null

抽象路径名的 路径名由路径名的前缀(如果有),以及路径名名称序列中最后一个名称以外的所有名称组成。如果名称序列为空,那么该路径名没有指定父目录。

返回:
此抽象路径名指定父目录的路径名字符串;如果此路径名没有指定父目录,则返回 null

getParentFile

public File getParentFile()
返回此抽象路径名父目录的抽象路径名;如果此路径名没有指定父目录,则返回 null

抽象路径名的 路径名由路径名的前缀(如果有),以及路径名名称序列中最后一个名称以外的所有名称组成。如果名称序列为空,那么该路径名没有指定父目录。

返回:
此抽象路径名指定父目录的抽象路径名;如果此路径名没有指定父目录,则返回 null
从以下版本开始:
1.2

getPath

public String getPath()
将此抽象路径名转换为一个路径名字符串。所得字符串使用默认名称分隔符分隔名称序列中的名称。

返回:
此抽象路径名的字符串形式

isAbsolute

public boolean isAbsolute()
测试此抽象路径名是否为绝对路径名。绝对路径名的定义与系统有关。在 UNIX 系统上,如果路径名的前缀是 "/",那么该路径名是绝对路径名。在 Microsoft Windows 系统上,如果路径名的前缀是后跟 "\\" 的盘符,或者是 "\\\\",那么该路径名是绝对路径名。

返回:
如果此抽象路径名是绝对路径名,则返回 true;否则返回 false

getAbsolutePath

public String getAbsolutePath()
返回此抽象路径名的绝对路径名字符串。

如果此抽象路径名已经是绝对路径名,则返回该路径名字符串,这与 getPath() 方法一样。如果此抽象路径名是空抽象路径名,则返回当前用户目录的路径名字符串,该目录由系统属性 user.dir 指定。否则,使用与系统有关的方式解析此路径名。在 UNIX 系统上,根据当前用户目录解析相对路径名,可使该路径名成为绝对路径名。在 Microsoft Windows 系统上,根据路径名指定的当前驱动器目录(如果有)解析相对路径名,可使该路径名成为绝对路径名;否则,可以根据当前用户目录解析它。

返回:
绝对路径名字符串,它与此抽象路径名表示相同的文件或目录
抛出:
SecurityException - 如果无法访问所需的系统属性值。
另请参见:
isAbsolute()

getAbsoluteFile

public File getAbsoluteFile()
返回此抽象路径名的绝对路径名形式。等同于 new File(this.getAbsolutePath())

返回:
绝对抽象路径名,它与此抽象路径名表示相同的文件或目录
抛出:
SecurityException - 如果无法访问所需的系统属性值。
从以下版本开始:
1.2

getCanonicalPath

public String getCanonicalPath()
                        throws IOException
返回此抽象路径名的规范路径名字符串。

规范路径名是绝对路径名,并且是惟一的。规范路径名的准确定义与系统有关。如有必要,此方法首先将路径名转换为绝对路径名,这与调用 getAbsolutePath() 方法的效果一样,然后用与系统相关的方式将它映射到其惟一路径名。这通常涉及到从路径名中移除多余的名称(比如 ".""..")、解析符号连接(对于 UNIX 平台),以及将驱动器号转换为标准大小写形式(对于 Microsoft Windows 平台)。

每个表示现存文件或目录的路径名都有一个惟一的规范形式。每个表示不存在文件或目录的路径名也有一个惟一的规范形式。不存在文件或目录路径名的规范形式可能不同于创建文件或目录之后同一路径名的规范形式。同样,现存文件或目录路径名的规范形式可能不同于删除文件或目录之后同一路径名的规范形式。

返回:
规范路径名字符串,它与此抽象路径名表示相同的文件或目录
抛出:
IOException - 如果发生 I/O 错误(可能是因为构造规范路径名需要进行文件系统查询)
SecurityException - 如果无法访问所需的系统属性值,或者存在安全管理器,且其 SecurityManager.checkRead(java.io.FileDescriptor) 方法拒绝对文件进行读访问
从以下版本开始:
JDK1.1

getCanonicalFile

public File getCanonicalFile()
                      throws IOException
返回此抽象路径名的规范形式。等同于 new File(this.getCanonicalPath())

返回:
规范路径名字符串,它与此抽象路径名表示相同的文件或目录
抛出:
IOException - 如果发生 I/O 错误(可能是因为构造规范路径名需要进行文件系统查询)
SecurityException - 如果无法访问所需的系统属性值,或者存在安全管理器,且其 SecurityManager.checkRead(java.io.FileDescriptor) 方法拒绝对文件进行读访问
从以下版本开始:
1.2

toURL

@Deprecated
public URL toURL()
          throws MalformedURLException
已过时。 此方法不会自动转义 URL 中的非法字符。建议新的代码使用以下方式将抽象路径名转换为 URL:首先通过 toURI 方法将其转换为 URI,然后通过 URI.toURL 方法将 URI 装换为 URL。

将此抽象路径名转换为一个 file: URL。该 URL 的具体形式与系统有关。如果可以确定此抽象路径名表示的文件是一个目录,那么所得 URL 将以斜杠结束。

返回:
表示等价文件 URL 的 URL 对象
抛出:
MalformedURLException - 如果无法将路径解析为 URL
从以下版本开始:
1.2
另请参见:
toURI(), URI, URI.toURL(), URL

toURI

public URI toURI()
构造一个表示此抽象路径名的 file: URI。

该 URI 的具体形式与系统有关。如果可以确定此抽象路径名表示的文件是一个目录,那么所得 URI 将以斜杠结束。

对于某个给定抽象路径名 f,可保证:

new File( f.toURI()).equals( f.getAbsoluteFile())
只要原始抽象路径名、URI 和新抽象路径名都是在同一 Java 虚拟机(或者它的不同调用)中创建的。但是,由于抽象路径名与系统有关的特性,当在某一操作系统上的虚拟机中创建的 file: URI 在不同操作系统上的虚拟机中被转换为抽象路径名时,这种关系通常是不成立的。

返回:
一个绝对分层 URI,由一个等于 "file" 的 scheme、表示此抽象路径名的 path,以及未定义的 authority、query 和 fragment 组件组成
抛出:
SecurityException - 如果不能访问请求的系统属性值。
从以下版本开始:
1.4
另请参见:
File(java.net.URI), URI, URI.toURL()

canRead

public boolean canRead()
测试应用程序是否可以读取此抽象路径名表示的文件。

返回:
当且仅当此抽象路径名指定的文件存在 可被应用程序读取时,返回 true;否则返回 false
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对文件进行读访问

canWrite

public boolean canWrite()
测试应用程序是否可以修改此抽象路径名表示的文件。

返回:
当且仅当文件系统实际包含此抽象路径名表示的文件 允许应用程序对该文件进行写入时,返回 true;否则返回 false
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkWrite(java.lang.String) 方法拒绝对文件进行写访问

exists

public boolean exists()
测试此抽象路径名表示的文件或目录是否存在。

返回:
当且仅当此抽象路径名表示的文件或目录存在时,返回 true;否则返回 false
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对文件或目录进行写访问

isDirectory

public boolean isDirectory()
测试此抽象路径名表示的文件是否是一个目录。

返回:
当且仅当此抽象路径名表示的文件存在 是一个目录时,返回 true;否则返回 false
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对文件进行读访问

isFile

public boolean isFile()
测试此抽象路径名表示的文件是否是一个标准文件。如果该文件不是一个目录,并且满足其他与系统有关的标准,那么该文件是标准 文件。由 Java 应用程序创建的所有非目录文件一定是标准文件。

返回:
当且仅当此抽象路径名表示的文件存在 是一个标准文件时,返回 true;否则返回 false
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对文件进行读访问

isHidden

public boolean isHidden()
测试此抽象路径名指定的文件是否是一个隐藏文件。隐藏 的具体定义与系统有关。在 UNIX 系统上,如果文件名以句点字符 ('.') 开头,则认为该文件被隐藏。在 Microsoft Windows 系统上,如果在文件系统中文件被标记为隐藏,则认为该文件被隐藏。

返回:
当且仅当此抽象路径名表示的文件根据底层平台约定是隐藏文件时,返回 true
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对文件进行读访问
从以下版本开始:
1.2

lastModified

public long lastModified()
返回此抽象路径名表示的文件最后一次被修改的时间。

返回:
表示文件最后一次被修改的时间的 long 值,用与时间点(1970 年 1 月 1 日,00:00:00 GMT)之间的毫秒数表示;如果该文件不存在,或者发生 I/O 错误,则返回 0L
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对文件进行读访问

length

public long length()
返回由此抽象路径名表示的文件的长度。如果此路径名表示一个目录,则返回值是不确定的。

返回:
此抽象路径名表示的文件的长度,以字节为单位;如果文件不存在,则返回 0L。对于表示特定于系统的实体(比如设备或管道)的路径名,某些操作系统可能返回 0L
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对文件进行读访问

createNewFile

public boolean createNewFile()
                      throws IOException
当且仅当不存在具有此抽象路径名指定名称的文件时,不可分地创建一个新的空文件。检查文件是否存在,若不存在则创建该文件,这是单个操作,对于其他所有可能影响该文件的文件系统活动来说,该操作是不可分的。

注:此方法不应该 用于文件锁定,因为所得协议可能无法可靠地工作。应该使用 FileLock 机制替代。

返回:
如果指定的文件不存在并成功地创建,则返回 true;如果指定的文件已经存在,则返回 false
抛出:
IOException - 如果发生 I/O 错误
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkWrite(java.lang.String) 方法拒绝对文件进行写访问
从以下版本开始:
1.2

delete

public boolean delete()
删除此抽象路径名表示的文件或目录。如果此路径名表示一个目录,则该目录必须为空才能删除。

返回:
当且仅当成功删除文件或目录时,返回 true;否则返回 false
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkDelete(java.lang.String) 方法拒绝对文件进行删除访问

deleteOnExit

public void deleteOnExit()
在虚拟机终止时,请求删除此抽象路径名表示的文件或目录。 文件(或目录)将以与注册相反的顺序删除。调用此方法删除已注册为删除的文件或目录无效。根据 Java 语言规范中的定义,只有在虚拟机正常终止时,才会尝试执行删除操作。

一旦请求了删除操作,就无法取消该请求。所以应小心使用此方法。

注:此方法不应该 用于文件锁定,因为所得协议可能无法可靠地工作。应该使用 FileLock 设施替代。

抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkDelete(java.lang.String) 方法拒绝对文件进行删除访问
从以下版本开始:
1.2
另请参见:
delete()

list

public String[] list()
返回一个字符串数组,这些字符串指定此抽象路径名表示的目录中的文件和目录。

如果此抽象路径名不表示一个目录,那么此方法将返回 null。否则返回一个字符串数组,每个数组元素对应目录中的每个文件或目录。表示目录本身及其父目录的名称不包括在结果中。每个字符串是一个文件名,而不是一条完整路径。

不保证所得数组中的相同字符串将以特定顺序出现,特别是不保证它们按字母顺序出现。

返回:
字符串数组,这些字符串指定此抽象路径名表示的目录中的文件和目录。如果目录为空,那么数组也将为空。如果此抽象路径名不表示一个目录,或者发生 I/O 错误,则返回 null
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对目录进行读访问

list

public String[] list(FilenameFilter filter)
返回一个字符串数组,这些字符串指定此抽象路径名表示的目录中满足指定过滤器的文件和目录。除了返回数组中的字符串必须满足过滤器外,此方法的行为与 list() 方法相同。如果给定 filternull,则接受所有名称。否则,当且仅当在此抽象路径名及其表示的目录中的文件名或目录名上调用过滤器的 FilenameFilter.accept(java.io.File, java.lang.String) 方法返回 true 时,该名称才满足过滤器。

参数:
filter - 文件名过滤器
返回:
字符串数组,这些字符串指定此抽象路径名表示的目录中给定 filter 能接受的文件和目录。如果目录为空,或者没有名称被过滤器接受,那么该数组将为空。如果抽象路径名不表示一个目录,或者发生 I/O 错误,则返回 null
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对目录进行读访问

listFiles

public File[] listFiles()
返回一个抽象路径名数组,这些路径名表示此抽象路径名表示的目录中的文件。

如果此抽象路径名不表示一个目录,那么此方法将返回 null。否则返回一个 File 对象数组,每个数组元素对应目录中的每个文件或目录。表示目录本身及其父目录的名称不包括在结果中。得到的每个抽象路径名都是根据此抽象路径名,使用 File(File, String) 构造方法构造的。所以,如果此路径名是绝对路径名,那么得到的每个路径名都是绝对路径名;如果此路径名是相对路径名,那么得到的每个路径名都是相对于同一目录的路径名。

不保证所得数组中的相同字符串将以特定顺序出现,特别是不保证它们按字母顺序出现。

返回:
抽象路径名数组,这些路径名表示此抽象路径名表示的目录中的文件和目录。如果目录为空,那么数组也将为空。如果抽象路径名不表示一个目录,或者发生 I/O 错误,则返回 null
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对目录进行读访问
从以下版本开始:
1.2

listFiles

public File[] listFiles(FilenameFilter filter)
返回抽象路径名数组,这些路径名表示此抽象路径名表示的目录中满足指定过滤器的文件和目录。除了返回数组中的路径名必须满足过滤器外,此方法的行为与 listFiles() 方法相同。如果给定 filternull,则接受所有路径名。否则,当且仅当在此抽象路径名及其表示的目录中的文件名或目录名上调用过滤器的 FilenameFilter.accept(java.io.File, java.lang.String) 方法返回 true 时,该路径名才满足过滤器。

参数:
filter - 文件名过滤器
返回:
抽象路径名数组,这些路径名表示此抽象路径名表示的目录中的文件和目录。如果目录为空,那么数组也将为空。如果此抽象路径名不表示一个目录,或者发生 I/O 错误,则返回 null
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对目录进行读访问
从以下版本开始:
1.2

listFiles

public File[] listFiles(FileFilter filter)
返回抽象路径名数组,这些路径名表示此抽象路径名表示的目录中满足指定过滤器的文件和目录。除了返回数组中的路径名必须满足过滤器外,此方法的行为与 listFiles() 方法相同。如果给定 filternull,则接受所有路径名。否则,当且仅当在路径名上调用过滤器的 FileFilter.accept(java.io.File) 方法返回 true 时,该路径名才满足过滤器。

参数:
filter - 文件过滤器
返回:
抽象路径名数组,这些路径名表示此抽象路径名表示的目录中的文件和目录。如果目录为空,那么数组也将为空。如果抽象路径名不表示一个目录,或者发生 I/O 错误,则返回 null
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对目录进行读访问
从以下版本开始:
1.2

mkdir

public boolean mkdir()
创建此抽象路径名指定的目录。

返回:
当且仅当已创建目录时,返回 true;否则返回 false
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkWrite(java.lang.String) 方法不允许创建指定的目录

mkdirs

public boolean mkdirs()
创建此抽象路径名指定的目录,包括所有必需但不存在的父目录。注意,此操作失败时也可能已经成功地创建了一部分必需的父目录。

返回:
当且仅当已创建目录以及所有必需的父目录时,返回 true;否则返回 false
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法不允许验证指定目录和所有必需的父目录是否存在;或者 SecurityManager.checkWrite(java.lang.String) 方法不允许创建指定的目录和所有必需的父目录

renameTo

public boolean renameTo(File dest)
重新命名此抽象路径名表示的文件。

此方法行为的许多方面都是与平台有关的:重命名操作无法将一个文件从一个文件系统移动到另一个文件系统,该操作不是不可分的,如果已经存在具有目标抽象路径名的文件,那么该操作可能无法获得成功。应该始终检查返回值,以确保重命名操作成功。

参数:
dest - 指定文件的新抽象路径名
返回:
当且仅当重命名成功时,返回 true;否则返回 false
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkWrite(java.lang.String) 方法拒绝对原路径名和新路径名进行写访问
NullPointerException - 如果参数 destnull

setLastModified

public boolean setLastModified(long time)
设置此抽象路径名指定的文件或目录的最后一次修改时间。

所有平台都支持将文件修改时间设置为最接近的秒数,而且一些平台会提供更精确的值。该参数将被截取,以满足受支持的精度。如果该操作成功,并且没有在文件上发生其他干扰操作,则下一次调用 lastModified() 方法将返回传递给此方法的 time 参数(可能被截取)。

参数:
time - 新的最后一次修改时间,用与时间点(1970 年 1 月 1 日,00:00:00 GMT)之间的毫秒数表示
返回:
当且仅当该操作成功时,返回 true;否则返回 false
抛出:
IllegalArgumentException - 如果该参数为负
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkWrite(java.lang.String) 方法拒绝对指定文件进行写访问
从以下版本开始:
1.2

setReadOnly

public boolean setReadOnly()
标记此抽象路径名指定的文件或目录,从而只能对其进行读操作。调用此方法后,可以保证在被删除或被标记为允许写访问之前,文件或目录不会发生更改。是否可以删除某个只读文件或目录则取决于底层系统。

返回:
当且仅当该操作成功时,返回 true;否则返回 false
抛出:
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkWrite(java.lang.String) 方法拒绝对指定文件进行写访问
从以下版本开始:
1.2

setWritable

public boolean setWritable(boolean writable,
                           boolean ownerOnly)
设置此抽象路径名的所有者或所有用户的写权限。

参数:
writable - 如果为 true,则设置允许写操作的访问权限;如果为 false,则不允许写操作。
ownerOnly - 如果为 true,则写权限只适用于所有者的写权限;否则适用于所有用户。如果底层文件系统不能区分所有者写权限与其他写权限,那么无论该参数为何值,写权限将适用于所有用户。
返回:
当且仅当操作成功时返回 true。如果用户不具有更改此抽象路径名访问权限的权限,那么操作将失败。
抛出:
SecurityException - 如果安全管理器存在且其 SecurityManager.checkWrite(java.lang.String) 方法拒绝对指定文件进行写访问。
从以下版本开始:
1.6

setWritable

public boolean setWritable(boolean writable)
设置此抽象路径名所有者写权限的一个便捷方法。

此方法 file.setWritable(arg) 形式的调用与以下调用的行为完全相同:

     file.setWritable(arg, true) 

参数:
writable - 如果为 true,则设置允许写操作的访问权限;如果为 false,则不允许写操作。
返回:
当且仅当操作成功时返回 true。如果用户不具有更改此抽象路径名访问权限的权限,那么操作将失败。
抛出:
SecurityException - 如果安全管理器存在且其 SecurityManager.checkWrite(java.lang.String) 方法拒绝对文件进行写访问。
从以下版本开始:
1.6

setReadable

public boolean setReadable(boolean readable,
                           boolean ownerOnly)
设置此抽象路径名的所有者或所有用户的读权限。

参数:
readable - 如果为 true,则设置允许读操作的访问权限;如果为 false,则不允许读操作。
ownerOnly - 如果为 true,则读权限只适用于所有者的读权限;否则适用于所有用户。如果底层文件系统不能区分所有者读权限与其他读权限,那么无论该参数为何值,读权限将适用于所有用户。
返回:
当且仅当操作成功时返回 true。如果用户不具有更改此抽象路径名访问权限的权限,那么操作将失败。如果 readablefalse,并且底层文件系统不实现读权限,那么操作也将失败。
抛出:
SecurityException - 如果安全管理器存在且其 SecurityManager.checkWrite(java.lang.String) 方法拒绝对文件进行写访问。
从以下版本开始:
1.6

setReadable

public boolean setReadable(boolean readable)
设置此抽象路径名所有者读权限的一个便捷方法。

此方法 file.setReadable(arg) 形式的调用与以下调用的行为完全相同:

     file.setReadable(arg, true) 

参数:
readable - 如果为 true,则设置允许读操作的访问权限;如果为 false,则不允许读操作。
返回:
当且仅当操作成功时返回 true。如果用户不具有更改此抽象路径名访问权限的权限,那么操作将失败。如果 readablefalse,并且底层文件系统不实现读权限,那么操作也将失败。
抛出:
SecurityException - 如果安全管理器存在且其 SecurityManager.checkWrite(java.lang.String) 方法拒绝对文件进行写访问。
从以下版本开始:
1.6

setExecutable

public boolean setExecutable(boolean executable,
                             boolean ownerOnly)
设置此抽象路径名的所有者或所有用户的执行权限。

参数:
executable - 如果为 true,则设置允许执行操作的访问权限;如果为 false,则不允许执行操作。
ownerOnly - 如果为 true,则执行权限只适用于所有者的执行权限;否则适用于所有用户。如果底层文件系统不能区分所有者执行权限与其他执行权限,那么无论该参数为何值,执行权限将适用于所有用户。
返回:
当且仅当操作成功时返回 true。如果用户不具有更改此抽象路径名访问权限的权限,那么操作将失败。如果 executablefalse,并且底层文件系统不实现执行权限,那么操作也将失败。
抛出:
SecurityException - 如果安全管理器存在且其 SecurityManager.checkWrite(java.lang.String) 方法拒绝对文件进行写访问。
从以下版本开始:
1.6

setExecutable

public boolean setExecutable(boolean executable)
设置此抽象路径名所有者执行权限的一个便捷方法。

此方法 file.setExcutable(arg) 形式的调用与以下调用的行为完全相同:

     file.setExecutable(arg, true) 

参数:
executable - 如果为 true,则设置允许执行操作的访问权限;如果为 false,则不允许执行操作。
返回:
当且仅当操作成功时返回 true。如果用户不具有更改此抽象路径名访问权限的权限,那么操作将失败。如果 executablefalse,并且底层文件系统不实现执行权限,那么操作也将失败。
抛出:
SecurityException - 如果安全管理器存在且其 SecurityManager.checkWrite(java.lang.String) 方法拒绝对文件进行写访问。
从以下版本开始:
1.6

canExecute

public boolean canExecute()
测试应用程序是否可以执行此抽象路径名表示的文件。

返回:
当且仅当抽象路径名存在 允许应用程序执行文件时返回 true
抛出:
SecurityException - 如果安全管理器存在且其 SecurityManager.checkExec(java.lang.String) 方法拒绝对文件进行执行访问。
从以下版本开始:
1.6

listRoots

public static File[] listRoots()
列出可用的文件系统根。

特定 Java 平台可以支持零个或更多个分层组织的文件系统。每个文件系统有一个 root 目录,可以从这里到达文件系统中的所有其他文件。例如,Windows 平台为每个活动驱动器提供了一个根目录;UNIX 平台只有一个根目录,即 "/"。可用文件系统根的设置受各种系统级操作的影响,比如可移动介质的插入和弹出,以及断开或卸载那些物理磁盘或虚拟磁盘。

此方法返回一个 File 对象数组,这些对象表示可用文件系统根的根目录。可以保证本地机器上物理存在的任何文件的规范路径名都以此方法返回的根之一开始。

位于其他一些机器上的文件的规范路径名是通过远程文件系统协议(比如 SMB 或 NFS)访问的,它们可能以此方法返回的根之一开始,也可能不是这样。如果远程文件的路径名在语法上无法与本地文件的路径名进行区分,那么它将以此方法返回的根之一开始。例如,此方法将返回表示 Windows 平台上映射为网络驱动器根目录的 File 对象,而不返回包含 UNC 路径名的 File 对象。

与此类中的大多数方法不同,此方法不抛出安全性异常。如果存在安全管理器,且其 SecurityManager.checkRead(java.lang.String) 方法拒绝对特定根目录进行读访问,那么该目录将不会出现在结果中。

返回:
表示可用文件系统根的 File 对象数组;如果无法确定根集,则返回 null。如果没有文件系统,那么该数组将为空。
从以下版本开始:
1.2

getTotalSpace

public long getTotalSpace()
返回此抽象路径名指定的分区大小。

返回:
分区的大小,以字节为单位;如果此抽象路径名没有指定分区,则返回 0L
抛出:
SecurityException - 如果安装了安全管理器,并且安全管理器拒绝 RuntimePermission("getFileSystemAttributes"),或者其 SecurityManager.checkRead(String) 方法拒绝对此抽象路径名指定的文件进行读访问
从以下版本开始:
1.6

getFreeSpace

public long getFreeSpace()
返回此抽象路径名指定的分区中未分配的字节数。

返回的未分配字节数是一个提示,而不是一个保证,只能使用这些字节的一部分。未分配字节数很可能在此调用后立即与实际相符。某些外部 I/O 操作可能使其与实际不符,这些操作包括那些在此虚拟机外部系统上进行的操作。此方法不保证对此文件系统的写操作将成功。

返回:
分区上的未分配字节数;如果抽象路径名没有指定分区,则返回 0L。返回值将小于等于 getTotalSpace() 返回的总文件系统大小。
抛出:
SecurityException - 如果安装了安全管理器,并且安全管理器拒绝 RuntimePermission("getFileSystemAttributes"),或者其 SecurityManager.checkRead(String) 方法拒绝对此抽象路径名指定的文件进行读访问
从以下版本开始:
1.6

getUsableSpace

public long getUsableSpace()
返回此抽象路径名指定的分区上可用于此虚拟机的字节数。若有可能,此方法将检查写权限和其他操作系统限制,因此与 getFreeSpace() 相比,此方法能更准确地估计可实际写入的新数据数。

返回的可用字节数是一个提示,而不是一个保证,只能使用这些字节的一部分。未分配字节数很可能在此调用后立即与实际相符。某些外部 I/O 操作可能使其与实际不符,这些操作包括那些在此虚拟机外部系统上进行的操作。此方法不保证对此文件系统的写操作将成功。

返回:
分区上的可用字节数;如果抽象路径名没有指定分区,则返回 0L。在此信息不可用的系统上,此方法等效于调用 getFreeSpace()
抛出:
SecurityException - 如果安装了安全管理器,并且安全管理器拒绝 RuntimePermission("getFileSystemAttributes"),或者其 SecurityManager.checkRead(String) 方法拒绝对此抽象路径名指定的文件进行读访问
从以下版本开始:
1.6

createTempFile

public static File createTempFile(String prefix,
                                  String suffix,
                                  File directory)
                           throws IOException

在指定目录中创建一个新的空文件,使用给定的前缀和后缀字符串生成其名称。如果此方法成功返回,则可以保证:

  1. 由返回的抽象路径名表示的文件在此方法被调用之前不存在。
  2. 此方法及其所有变体都不会在虚拟机的当前调用中再次返回相同的抽象路径名。
此方法只提供了临时文件的部分功能。要安排自动删除此方法创建的文件,可使用 deleteOnExit() 方法。

prefix 参数至少必须是三个字节长。建议前缀使用一个短的、有意义的字符串,比如 "hjb""mail"suffix 参数可以为 null,在这种情况下,将使用后缀 ".tmp"

要创建新文件,可能首先要调整前缀和后缀,使其满足底层平台的限制。如果前缀太长,则将它截断,但前三个字符将始终保留。如果后缀太长,则将它截断,但如果它以句点字符 ('.') 开始,则该句点以及后跟的前三个字符将始终保留。进行了这些调整后,通过连接前缀、五个或更多个内部生成的字符以及后缀,便生成了新文件的名称。

如果 directory 参数为 null,则使用与系统有关的默认临时文件目录。默认临时文件目录由系统属性 java.io.tmpdir 指定。在 UNIX 系统上,此属性的默认值通常是 "/tmp""/var/tmp";在 Microsoft Windows 系统上,该值通常是 "C:\\WINNT\\TEMP"。在调用 Java 虚拟机时,可为此系统属性提供不同的值,但不保证使用程序更改此属性会对此方法使用的临时目录产生影响。

参数:
prefix - 用于生成文件名的前缀字符串;必须至少是三字符长
suffix - 用于生成文件名的后缀字符串;可以为 null,在这种情况下,将使用后缀 ".tmp"
directory - 将创建的文件所在的目录;如果使用默认临时文件目录,则该参数为 null
返回:
表示新建空文件的抽象路径名
抛出:
IllegalArgumentException - 如果 prefix 参数包含的字符少于三个
IOException - 如果无法创建文件
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkWrite(java.lang.String) 方法不允许创建文件
从以下版本开始:
1.2

createTempFile

public static File createTempFile(String prefix,
                                  String suffix)
                           throws IOException
在默认临时文件目录中创建一个空文件,使用给定前缀和后缀生成其名称。调用此方法等同于调用 createTempFile(prefix, suffix, null)

参数:
prefix - 用于生成文件名的前缀字符串;必须至少是三字符长
suffix - 用于生成文件名的后缀字符串;可以为 null,在这种情况下,将使用后缀 ".tmp"
返回:
表示新建空文件的抽象路径名
抛出:
IllegalArgumentException - 如果 prefix 参数包含的字符少于三个
IOException - 如果无法创建文件
SecurityException - 如果存在安全管理器,且其 SecurityManager.checkWrite(java.lang.String) 方法不允许创建文件
从以下版本开始:
1.2

compareTo

public int compareTo(File pathname)
按字母顺序比较两个抽象路径名。此方法定义的顺序取决于底层系统。在 UNIX 系统上,比较路径名时,字母大小写通常很重要,而在 Microsoft Windows 系统上,这通常不重要。

指定者:
接口 Comparable<File> 中的 compareTo
参数:
pathname - 将与此抽象路径名进行比较的抽象路径名
返回:
如果该参数等于此抽象路径名,则返回零;如果此抽象路径名在字母顺序上小于该参数,则返回小于零的值;如果此抽象路径名在字母顺序上大于该参数,则返回大于零的值
从以下版本开始:
1.2

equals

public boolean equals(Object obj)
测试此抽象路径名与给定对象是否相等。当且仅当该参数不是 null,而是一个与此抽象路径名表示相同的文件或目录的抽象路径名时,返回 true。两个抽象路径名是否相等取决于底层系统。在 UNIX 系统上,比较路径名时,字母大小写通常很重要,而在 Microsoft Windows 系统上,这通常不重要。

覆盖:
Object 中的 equals
参数:
obj - 要与此抽象路径名进行比较的对象
返回:
当且仅当对象相同时,返回 true;否则返回 false
另请参见:
Object.hashCode(), Hashtable

hashCode

public int hashCode()
计算此抽象路径名的哈希码。因为抽象路径名的相等性与系统有关,所以对其哈希码的计算也与系统有关。在 UNIX 系统上,抽象路径名的哈希码等于其路径名字符串和十进制值 1234321 的哈希码的异或。在 Microsoft Windows 系统上,哈希码等于其转换为小写的路径名字符串和十进制值 1234321 的哈希码的异或。在将路径名字符串转换为小写时不考虑语言环境。

覆盖:
Object 中的 hashCode
返回:
此抽象路径名的哈希码
另请参见:
Object.equals(java.lang.Object), Hashtable

toString

public String toString()
返回此抽象路径名的路径名字符串。该字符串就是 getPath() 方法返回的字符串。

覆盖:
Object 中的 toString
返回:
此抽象路径名的字符串形式

JavaTM Platform
Standard Ed. 6

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策