java io PrintStream源码分析

目录

简介

字段autoFlush,trouble,formatter,textOut,charOut,方法requireNonNull,toCharset

3个私有构造函数，7个公共构造函数

字段closing,方法ensureOpen,flush,close,checkError,setError,clearError

2个公共write方法，2个私有write方法，newLine方法

9个print方法

10个println方法

2个printf方法，2个format方法，3个append方法

---

简介

package java.io;

import java.util.Formatter;
import java.util.Locale;
import java.nio.charset.Charset;
import java.nio.charset.IllegalCharsetNameException;
import java.nio.charset.UnsupportedCharsetException;

/**
 * PrintStream向另一个输出流添加功能，即方便地打印各种数据值的表示的能力。
 * 还提供了其他两个特性。
 * 与其他outputstream不同，PrintStream从不抛出IOException;
 * 相反，异常情况仅仅设置了一个可以通过checkError方法进行测试的内部标志。
 * 可选地，可以创建一个自动刷新的PrintStream;
 * 这意味着在写入字节数组、调用println方法之一或写入换行字符或字节('\n')之后自动调用flush方法。
 *
 * <p> PrintStream打印的所有字符都使用平台的默认字符编码转换为字节。
 * 应该在需要写入字符而不是字节的情况下使用PrintWriter类。
 *
 * @author     Frank Yellin
 * @author     Mark Reinhold
 * @since      JDK1.0
 */

public class PrintStream extends FilterOutputStream
    implements Appendable, Closeable

字段autoFlush,trouble,formatter,textOut,charOut,方法requireNonNull,toCharset

	// 是否自动刷新的标志
    private final boolean autoFlush;
    // 表示类内部是否报错的标志
    private boolean trouble = false;
    private Formatter formatter;

    /**
     * 同时跟踪文本输出流和字符输出流，
     * 以便在不刷新整个流的情况下刷新它们的缓冲区。
     */
    private BufferedWriter textOut;
    private OutputStreamWriter charOut;

    /**
     * 在这里显式声明requireNonNull，以避免在系统初始化期间加载java.util.Objects.requireNonNull。
     */
    private static <T> T requireNonNull(T obj, String message) {
        if (obj == null)
            throw new NullPointerException(message);
        return obj;
    }

    /**
     * 返回给定字符集名称的Charset对象。
     * @throws NullPointerException          is csn is null
     * @throws UnsupportedEncodingException  if the charset is not supported
     */
    private static Charset toCharset(String csn)
        throws UnsupportedEncodingException
    {
        requireNonNull(csn, "charsetName");
        try {
        	// 调用Charset的方法
            return Charset.forName(csn);
        } catch (IllegalCharsetNameException|UnsupportedCharsetException unused) {
            // UnsupportedEncodingException should be thrown
            throw new UnsupportedEncodingException(csn);
        }
    }

3个私有构造函数，7个公共构造函数

    /* 私有构造器 */
    private PrintStream(boolean autoFlush, OutputStream out) {
    	// 以out作为底层的out
        super(out);
        // 设置自动刷新
        this.autoFlush = autoFlush;
        // 把自己，PrintStream作为参数，给OutputStreamWriter，然后赋值给charOut
        // charOut = new OutputStreamWriter(new PrintStream(out))
        this.charOut = new OutputStreamWriter(this);
        // 把charOut，OutputStreamWriter作为参数，给BufferedWriter，然后赋值给textOut
        // textOut = new BufferedWriter(new OutputStreamWriter(new PrintStream(out)))
        this.textOut = new BufferedWriter(charOut);
    }

    private PrintStream(boolean autoFlush, OutputStream out, Charset charset) {
        super(out);
        this.autoFlush = autoFlush;
        // charset作为参数，传递给OutputStreamWriter，charOut
        this.charOut = new OutputStreamWriter(this, charset);
        this.textOut = new BufferedWriter(charOut);
    }

    /* 私有构造函数的变体，以便在计算OutputStream实参之前验证给定的字符集名称。
     * 由构造函数使用，它创建一个带有字符集名称的FileOutputStream。
     */
    private PrintStream(boolean autoFlush, Charset charset, OutputStream out)
        throws UnsupportedEncodingException
    {
        this(autoFlush, out, charset);
    }

    /**
     * 创建一个新的打印流。此流不会自动刷新。
     *
     * @param  out        The output stream to which values and objects will be
     *                    printed
     *
     * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream)
     */
    public PrintStream(OutputStream out) {
        this(out, false);
    }

    /**
     * 创建一个新的打印流。
     *
     * @param  out        The output stream to which values and objects will be
     *                    printed
     * @param  autoFlush  A boolean; if true, the output buffer will be flushed
     *                    whenever a byte array is written, one of the
     *                    <code>println</code> methods is invoked, or a newline
     *                    character or byte (<code>'\n'</code>) is written
     *
     * @see java.io.PrintWriter#PrintWriter(java.io.OutputStream, boolean)
     */
    public PrintStream(OutputStream out, boolean autoFlush) {
        this(autoFlush, requireNonNull(out, "Null output stream"));
    }

    /**
     * 创建一个新的打印流。
     *
     * @param  out        The output stream to which values and objects will be
     *                    printed
     * @param  autoFlush  A boolean; if true, the output buffer will be flushed
     *                    whenever a byte array is written, one of the
     *                    <code>println</code> methods is invoked, or a newline
     *                    character or byte (<code>'\n'</code>) is written
     * @param  encoding   The name of a supported
     *                    <a href="../lang/package-summary.html#charenc">
     *                    character encoding</a>
     *
     * @throws  UnsupportedEncodingException
     *          If the named encoding is not supported
     *
     * @since  1.4
     */
    public PrintStream(OutputStream out, boolean autoFlush, String encoding)
        throws UnsupportedEncodingException
    {
        this(autoFlush,
             requireNonNull(out, "Null output stream"),
             toCharset(encoding));
    }

    /**
     * 使用指定的文件名创建一个新的打印流，不需要自动刷新行。
     * 这个方便的构造函数创建必要的中间值OutputStreamWriter，
     * 它将使用Java虚拟机的这个实例的默认charset对字符进行编码。
     *
     * @param  fileName
     *         The name of the file to use as the destination of this print
     *         stream.  If the file exists, then it will be truncated to
     *         zero size; otherwise, a new file will be created.  The output
     *         will be written to the file and is buffered.
     *
     * @throws  FileNotFoundException
     *          If the given file object does not denote an existing, writable
     *          regular file and a new regular file of that name cannot be
     *          created, or if some other error occurs while opening or
     *          creating the file
     *
     * @throws  SecurityException
     *          If a security manager is present and {@link
     *          SecurityManager#checkWrite checkWrite(fileName)} denies write
     *          access to the file
     *
     * @since  1.5
     */
    public PrintStream(String fileName) throws FileNotFoundException {
        this(false, new FileOutputStream(fileName));
    }

    /**
     * 使用指定的文件名创建一个新的打印流，不需要自动刷新行。
     * 这个方便的构造函数创建必要的中间值OutputStreamWriter，
     * 它将使用提供的charset编码字符。
     *
     * @param  fileName
     *         The name of the file to use as the destination of this print
     *         stream.  If the file exists, then it will be truncated to
     *         zero size; otherwise, a new file will be created.  The output
     *         will be written to the file and is buffered.
     *
     * @param  csn
     *         The name of a supported {@linkplain java.nio.charset.Charset
     *         charset}
     *
     * @throws  FileNotFoundException
     *          If the given file object does not denote an existing, writable
     *          regular file and a new reg