[转]Commons IO 官方文档

原文地址:http://ifeve.com/commons-io/

本文翻译自 Commons IO 官方文档 译者:MagicWolf

Common IO 是一个工具库，用来帮助开发IO功能 它包括6个主要部分

• Utility classes – 包括一些静态方法来执行常用任务
• Input – InputStream 和 Reader 实现
• Output – OutputStream 和 Writer 实现
• Filters – 多种文件过滤器实现(定义了 IOFileFilter接口,同时继承了 FileFilter 和 FilenameFilter 接口)
• Comparators – 用于文件比较的多种java.util.Comparatot实现

发行版本

---

• Commons IO 2.5 (requires JDK 1.6+)
• Commons IO 2.4 (requires JDK 1.6+)
• Commons IO 2.2 (requires JDK 1.5+)

用户指南

---

Commons-IO 包括 工具类 (utility classes), 字节序列类 (endian classes), 行迭代器 (line iterator), 文件过滤器 (file filters),文件比较器 (file comparators) 和 流实现 (stream implementations).

Utility classes

IOUtils

IOUtils 包含一些工具类,用于处理读,写和拷贝,这些方法基于 InputStream, OutputStream, Reader 和 Writer工作.

例如，思考一个任务，从URL中读取byte数据，并打印。通常会这样做:

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);
}

在某些应用领域，例如IO操作中是很常见的,这个类可以节省很多时间。并且你可以依赖于经过全面测试的代码。

对于这类的代码,灵活性和速度是最重要的。然而你也应该明白这么做的限制。使用以上的方式读取一个1GB的文件将会试图创造一个1GB字符串对象

FileUtils

FileUtils 包含一些工具类,它们基于File对象工作，包括读，写，拷贝和比较文件

例如逐行读取整个文件你可以使用:

File file = new File("/commons/io/project.properties");
List lines = FileUtils.readLines(file, "UTF-8");

FilenameUtils

FilenameUtils包含一些工具类,它们基于文件名工作而不是File对象。这个类旨在 在Unix和Windows环境下保持一致,帮助在两个环境下过渡(如从开发环境到生成环境)

例如，正常化文件名，删除..片段:

String filename = "C:/commons/io/../lang/project.xml";
String normalized = FilenameUtils.normalize(filename);
// result is "C:/commons/lang/project.xml"

FileSystemUtils

FileSystemUtils包含一些工具类，基于文件系统访问功能不被JDK支持。目前，只有一个方法就是得到驱动器空余空间。注意这使用命令行而不是 native code。

例如得到驱动器空余空间:

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

Endian classes

不同的计算机架构对应字节序采用不同的约定,在所谓的”小端”架构(例如Intel)，低位字节被存储在内存的最低字节,之后的字节在高地址。对于”大端”架构(如Motoroal),情况相反。

在这个包中有两个相关联的类:

• EndianUtils 包含静态方法来交换Java基本类型和流的字节序
• SwappedDataInputStream实现了DataInput接口。可以从文件中读取非本地字节序。

Line iterator

org.apache.commons.io.LineIterator类提供类灵活的方式操作基于行的文件。通过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接口。除此之外还提供了一系列可以使用的IOFileFilter接口实现，包括允许你组合其他过滤器。这些过滤器可以用来遍历文件或在FileDialog中使用。

详情见 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 包中包含一些有用的流实现。他们包括:

• Null output stream – 默默吸收所有发给它的数据
• Tee output stream – 发送输出数据给两个流而不是一个
• Byte array output stream – 这是一个比JDK更快的版本
• Counting streams – 计算通过的字节数
• Proxy streams – 在代理中委托正确的方法
• Lockable writer – 使用锁文件提供写入同步

详情见 input 和 output 包的Javadoc。

最佳实践

---

本文档提供一些在IO领域的最佳实践

java.io.File

通常，你要处理文件和文件名。有很多地方可能出错：

• 一个类在Uinx下正常工作但是在Windows下不工作(反之亦然)
• 由于重复或丢失路径分隔符造成无效的文件名
• 等等

这些都是不使用字符串类型文件名的充分理由。使用 java.io.File 可以很好的处理上述情况。因此，我们的最佳实践建议对文件名使用 java.io.File 代替字符串来避免平台依赖。

commons-io 1.1开始包含一个专门用于文件名的处理类 – FilenameUtils。这会处理很多这类文件名问题，但是我们仍然建议尽可能的使用 java.io.File 对象

让我们来看一个例子:

public static String getExtension(String filename) {
    int index = filename.lastIndexOf('.');
    if (index == -1) {
        return "";
    } else {
        return filename.substring(index + 1);
    }
}

很容易?是的，但是如果传入一个全路径而不只是文件名会发生什么?考虑一下，完全合法的路径: “C:Tempdocumentation.newREADME”。这个方法将会返回”newREADME”，绝对不是你想要的

请使用 java.io.File 代替字符串作为文件名。这个类提供的方法经过了良好的测试。在 FileUtil你会发现其他关于 java.io.File 有用的工具方法。

String tmpdir = "/var/tmp";
String tmpfile = tmpdir + System.getProperty("file.separator") + "test.tmp";
InputStream in = new java.io.FileInputStream(tmpfile);

替代

File tmpdir = new File("/var/tmp");
File tmpfile = new File(tmpdir, "test.tmp");
InputStream in = new java.io.FileInputStream(tmpfile);

Buffering streams

IO性能很多情况下取决于缓冲策略。通常以512或1024比特读取数据块会相当快，因为这些大小的数据块和硬盘在文件系统中的数据块大小或文件系统缓存很搭配。但是如果你只需要读取结果字节那么性能会有显著下降

确保你在读取或写入流时正确的进行缓冲，特别是使用文件时，只在 BufferedInputStream 上包装 FileInputStream

InputStream in = new java.io.FileInputStream(myfile);
try {
    in = new java.io.BufferedInputStream(in);
    in.read(.....
} finally {
    IOUtils.closeQuietly(in);
}

注意不要缓冲一个已经被缓冲的流。一些组件例如 XML 解析器可能自己缓冲，所以装饰传递给 XML 解析器的InputStream只会拖慢的代码。如果你使用我们的 CopyUtils 或者 IOUitls你不需要另外缓冲，你使用的代码在复制过程的已经缓冲。经常检查Javadocs中的信息。另一种情况，当你向ByteArrayOutputStream中写入时，缓冲不是必须的，因为你只写入内存。

原创文章，转载请注明： 转载自并发编程网 – ifeve.com本文链接地址: Commons IO 官方文档