apache commons-io 用户手册

用户手册（User guide）

翻译：侯骏雄（QQ：2442278700）

Commons-IO 包括 工具类（utility classes）, 尾端类（endian classes）, 行迭代器（line iterator）, 文件过滤器（file filters）, 文件比较器（file comparators） 以及 输入输出流实现类（stream implementations）。【译注：此处的文件（file）指Java中的File类，是广义的文件，其包括文件夹、字节流、字符流以及侠义的文件，需要读者区别理解。】

想了解更多信息，可以查看 javadocs。

工具类（Utility classes）

输入输出流工具类（IOUtils）

输入输出流工具类（IOUtils） 包含读取、写入、复制的工具方法。这些方法简化了字节输入流（InputStream）,字节输出流（OutputStream）, 字符输入流（Reader） 以及 字符输出流（Writer）的使用。

例如, 实现一个从统一资源定位符（URL）读取字节流（bytes），并打印的业务。这个业务通常可以如下般实现：

InputStream in = new URL( "http://commons.apache.org" ).openStream();

try {

InputStreamReader inR = new InputStreamReader( in );

BufferedReader buf = new BufferedReader( inR );

String line;

while ( ( line = buf.readLine() ) != null ) {

System.out.println( line );

}

} finally {

in.close();

}

使用输入输出流工具类（IOUtils）可以如下实现：

InputStream in = new URL( "http://commons.apache.org" ).openStream();

try {

System.out.println( IOUtils.toString( in ) );

} finally {

IOUtils.closeQuietly(in);

}

在某些输入输出操作频繁（common）的应用程序域（application domain），这个类可以节省大量处理时间。而且你可以信赖这些经过反复测试的代码。

对于像这种工具类代码来说可扩展性（flexibility）以及执行效率（speed）是首要的。然而你也应该了解这种方案的局限性。使用以上的技术来读取一个1GB的文件将导致系统尝试创建一个1GB的字符串（String）对象！

文件工具类(FileUtils)

文件工具类（FileUtils）包含辅助处理文件（File）对象的工具方法。这包括读取、写入、复制以及比较文件。

例如一行一行地（line by line）读取（read）一整个文件你可以如下使用：

File file = new File("/commons/io/project.properties");

List lines = FileUtils.readLines(file, "UTF-8");

文件名工具类（FilenameUtils）

文件名工具类（FilenameUtils） 包含不通过文件（File）对象来辅助处理文件名的工具方法。这个类致力于保证程序在Unix与Windows之间的效果一致，并帮助程序在这些环境之间互换(例如从开发环境部署到生产环境)。

例如标准化地（normalize）去掉一个文件名的双点部分：

String filename = "C:/commons/io/../lang/project.xml";

String normalized = FilenameUtils.normalize(filename);

// result is "C:/commons/lang/project.xml"

文件系统工具类(FileSystemUtils)

文件系统工具类（FileSystemUtils） 包含辅助处理接入JDK不支持的文件系统（file system）功能工具方法。目前,唯一的方法是在一个设备上获取可用空间（free space）。注意这个方法使用命令行（command line）实现，不是原生（native）代码。

例如查找在一个设备上的可用空间（free space）：

long freeSpace = FileSystemUtils.freeSpace("C:/");

尾端类（Endian classes）

不同CPU架构采用不同字节序协议。在所谓的“小端字节序”（Little Endian）架构(如英特尔（Intel）)，低位字节被存储在最低的内存地址（the lowest address），随后的字节流（bytes）在更高的内存地址（higher address）。对于“大端字节序”（Big Endian）架构(如 摩托罗拉（Motorola）)，情况这是相反的。

有两个类在这个特性上是关联的：

尾端类（EndianUtils） 包含转换（swap）Java基本数据类型（primitives）字节序（Endian-ness）以及输入输出流字节序（Endian-ness）的静态方法。

转换数据字节输入流（SwappedDataInputStream） 是一个DataInput接口的实现类。使用该类，开发人员可以从文件中忽视字节序地（non-native Endian-ness）读取（read）数据。

更多信息，查看http://www.cs.umass.edu/~verts/cs32/endian.html

行迭代器（Line iterator）

org.apache.commons.io.LineIterator 提供一个可扩展的（flexible）方法辅助处理一个基于行的文件。它的对象可以被直接创建，或通过文件工具类（FileUtils）或输入输出流工具类（IOUtils）的工厂方法创建。推荐的使用方式是：

LineIterator it = FileUtils.lineIterator(file, "UTF-8");

try {

while (it.hasNext()) {

String line = it.nextLine();

/// do something with line

}

} finally {

LineIterator.closeQuietly(iterator);

}

文件过滤器（File filters）

org.apache.commons.io.filefilter 包定义了一个接口(输入输出文件过滤器（IOFileFilter）)，它结合java.io.FileFilter和的java.io.FilenameFilter方法。此外该包还提供一系列随时可用的（ready-to-use）输入输出文件过滤器（IOFileFilter）实现类。并且允许你组合其他更多过滤器（filter）。例如这些过滤器（filter）可以被用于展示文件树或文件弹窗。

查看文件过滤器（filefilter） 包javadoc以获得更多细节。

文件比较器（File comparators）

org.apache.commons.io.comparator 包提供大量用于java.io.File的java.util.Comparator实现类。例如这些比较器可以被用于文件列表以及文件数组的排序。

查看比较器（comparator） 包javadoc以获得更多细节。

输入输出流（Streams）

org.apache.commons.io.input 以及 org.apache.commons.io.output 包包含许多有用的输入输出流（streams）实现类。他们包括：

桩字节输出流（Null output stream） - 它静静地（silently）接收（absorb）所有发送给它的数据

三通字节输出流（Tee output stream） - 它从一个输入流的数据发送到两个输出流中

字节数组字节输出流（Byte array output stream） - 它是比JDK类更快的版本

计数器输入输出流（Counting streams） - 它计算字节流（bytes）通过的数量

代理输入输出流（Proxy streams） - 它代理一个输入输出流并调用适当的（correct）方法

加锁字符输出流（Lockable writer） - 它通过使用一个文件锁（lock file）提供同步（synchronization）写功能

查看字节输入流（input） 或 字节输出流（output） 包javadoc以获得更多细节。