/*
* Copyright (c) 2001, 2005, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/*
*/
package sun.nio.cs;
import java.io.*;
import java.nio.*;
import java.nio.channels.*;
import java.nio.charset.*;
// 输出流编码器：将字符序列编码为字节后，写入到字节输出流
public class StreamEncoder extends Writer {
private static final int DEFAULT_BYTE_BUFFER_SIZE = 8192;
private CharsetEncoder encoder; // 字符编码器。字符进来，字节出去，完成对字符序列的编码操作
private Charset cs; // 字符编码器对应的字符集
/** Exactly one of these is non-null */
private final OutputStream out; // 字节输出流(最终输出流)
/** Factory for java.nio.channels.Channels.newWriter */
private WritableByteChannel ch; // 输出目的地关联的通道
private ByteBuffer bb; // 内部使用的堆内存缓冲区，存储解码后的字节
/**
* All synchronization and state/argument checking is done in these public methods;
* the concrete stream-encoder subclasses defined below need not do any such checking.
* Leftover first char in a surrogate pair
*/
private boolean haveLeftoverChar = false; // 上一轮编码后，是否残留一个未处理字符
private char leftoverChar; // 保存一个未处理字符
private CharBuffer lcb = null; // 临时存储待处理的字符
private volatile boolean closed;
/*▼ 构造器 ████████████████████████████████████████████████████████████████████████████████┓ */
private StreamEncoder(OutputStream out, Object lock, Charset cs) {
this(out, lock, cs.newEncoder().onMalformedInput(CodingErrorAction.REPLACE).onUnmappableCharacter(CodingErrorAction.REPLACE));
}
private StreamEncoder(OutputStream out, Object lock, CharsetEncoder enc) {
super(lock);
this.out = out;
this.ch = null;
this.cs = enc.charset();
this.encoder = enc;
/* This path disabled until direct buffers are faster */
// 已禁用此途径，将来文件使用直接缓冲区更快时，可能会解禁此途径
if(false && out instanceof FileOutputStream) {
// 获取当前文件输入流关联的只读通道
ch = ((FileOutputStream) out).getChannel();
if(ch != null) {
// 创建直接内存缓冲区DirectByteBuffer
bb = ByteBuffer.allocateDirect(DEFAULT_BYTE_BUFFER_SIZE);
}
}
if(ch == null) {
// 创建堆内存缓冲区HeapByteBuffer
bb = ByteBuffer.allocate(DEFAULT_BYTE_BUFFER_SIZE);
}
}
private StreamEncoder(WritableByteChannel ch, CharsetEncoder enc, int mbc) {
this.out = null;
this.ch = ch;
this.cs = enc.charset();
this.encoder = enc;
this.bb = ByteBuffer.allocate(mbc<0 ? DEFAULT_BYTE_BUFFER_SIZE : mbc);
}
/*▲ 构造器 ████████████████████████████████████████████████████████████████████████████████┛ */
/*▼ 写 ████████████████████████████████████████████████████████████████████████████████┓ */
// 将指定的字符写入到输出流
public void write(int c) throws IOException {
char[] cbuf = new char[1];
cbuf[0] = (char) c;
write(cbuf, 0, 1);
}
// 将字符数组cbuf中off处起的len个字符写入到输出流
public void write(char[] cbuf, int off, int len) throws IOException {
synchronized(lock) {
ensureOpen();
if((off<0) || (off>cbuf.length) || (len<0) || ((off + len)>cbuf.length) || ((off + len)<0)) {
throw new IndexOutOfBoundsException();
} else if(len == 0) {
return;
}
implWrite(cbuf, off, len);
}
}
// 将字符串str中off处起的len个字符写入到输出流
public void write(String str, int off, int len) throws IOException {
/* Check the len before creating a char buffer */
if(len<0) {
throw new IndexOutOfBoundsException();
}
char[] cbuf = new char[len];
str.getChars(off, off + len, cbuf, 0);
write(cbuf, 0, len);
}
// 将字符缓冲区cb中的字符写入到输出流
public void write(CharBuffer cb) throws IOException {
int position = cb.position();
try {
synchronized(lock) {
ensureOpen();
// 从cb中读取字符，并对其编码后写到输出流
implWrite(cb);
}
} finally {
cb.position(position);
}
}
/*▲ 写 ████████████████████████████████████████████████████████████████████████████████┛ */
/*▼ 杂项 ████████████████████████████████████████████████████████████████████████████████┓ */
// 刷新缓冲区：将内部缓冲区中的字节写到最终输出流中(该操作不会刷新最终输出流)
public void flushBuffer() throws IOException {
synchronized(lock) {
if(isOpen()) {
implFlushBuffer();
} else {
throw new IOException("Stream closed");
}
}
}
// 刷新流，不仅刷新当前输出流编码器的内部缓冲区，还刷新最终字节输出流的内部缓冲区(如果存在)
public void flush() throws IOException {
synchronized(lock) {
ensureOpen();
implFlush();
}
}
// 关闭输出流编码器
public void close() throws IOException {
synchronized(lock) {
if(closed) {
return;
}
implClose();
closed = true;
}
}
// 返回字节编码器使用的字符集名称
public String getEncoding() {
if(isOpen()) {
return encodingName();
}
return null;
}
/*▲ 杂项 ████████████████████████████████████████████████████████████████████████████████┛ */
/*▼ 工厂方法 ████████████████████████████████████████████████████████████████████████████████┓ */
// 返回输出流编码器，out是输出目的地
public static StreamEncoder forOutputStreamWriter(OutputStream out, Object lock, String charsetName) throws UnsupportedEncodingException {
String csn = charsetName;
if(csn == null)
csn = Charset.defaultCharset().name();
try {
if(Charset.isSupported(csn)) {
return new StreamEncoder(out, lock, Charset.forName(csn));
}
} catch(IllegalCharsetNameException x) {
}
throw new UnsupportedEncodingException(csn);
}
// 返回输出流编码器，out是输出目的地
public static StreamEncoder forOutputStreamWriter(OutputStream out, Object lock, Charset cs) {
return new StreamEncoder(out, lock, cs);
}
// 返回输出流编码器，out是输出目的地
public static StreamEncoder forOutputStreamWriter(OutputStream out, Object lock, CharsetEncoder enc) {
return new StreamEncoder(out, lock, enc);
}
// 返回输出流编码器，ch是输出目的地，minBufferCap是内部缓冲区的最小容量
public static StreamEncoder forEncoder(WritableByteChannel ch, CharsetEncoder enc, int minBufferCap) {
return new StreamEncoder(ch, enc, minBufferCap);
}
/*▲ 工厂方法 ████████████████████████████████████████████████████████████████████████████████┛ */
// 从字符数组cbuf中off处起读取len个字符，并对其编码后写到输出流
void implWrite(char[] cbuf, int off, int len) throws IOException {
// 包装字符数组cbuf到缓冲区cb
CharBuffer cb = CharBuffer.wrap(cbuf, off, len);
// 从cb中读取字符，并对其编码后写到输出流
implWrite(cb);
}
// 从cb中读取字符，并对其编码后写到输出流
void implWrite(CharBuffer cb) throws IOException {
// 如果包含至少一个未处理字符
if(haveLeftoverChar) {
/*
* 对上一轮写入中残留下的那个字符进行编码，并将编码后的字节后写入到输出流
* 当发生下溢时，不会抛异常，因为可以期待后续的输入
*/
flushLeftoverChar(cb, false);
}
// 如果缓冲区还有未读字符
while(cb.hasRemaining()) {
/*
* 从给定的输入缓冲区cb中编码尽可能多的字符，将结果写入给定的输出缓冲区bb。
* 当发生下溢时，可能还会有后续的输入，不会抛异常
*/
CoderResult cr = encoder.encode(cb, bb, false);
/*
* 发生下溢，输出缓冲区bb仍有空闲
*
* 出现此情形很可能遇到了四字节符号
*/
if(cr.isUnderflow()) {
assert (cb.remaining()<=1) : cb.remaining();
// 如果ch中仅剩一个未读的字符了
if(cb.remaining() == 1) {
// 暂存该未处理的字符
haveLeftoverChar = true;
leftoverChar = cb.get();
}
break;
}
// 发生上溢，输出缓冲区已经满了
if(cr.isOverflow()) {
assert bb.position()>0;
// 将内部缓冲区中的字节写到最终输出流中
writeBytes();
continue;
}
cr.throwException();
}
}
// 刷新流，不仅刷新当前输出流编码器的内部缓冲区，还刷新字节输出流(的内部缓冲区)
void implFlush() throws IOException {
implFlushBuffer();
if(out != null) {
out.flush();
}
}
// 刷新缓冲区：将内部缓冲区中的字节写到最终输出流中
void implFlushBuffer() throws IOException {
// 如果内部缓冲区中包含数据
if(bb.position()>0) {
// 将内部缓冲区中的字节写到最终输出流中
writeBytes();
}
}
// 关闭输出流编码器
void implClose() throws IOException {
/*
* 对上一轮写入中残留下的那个字符进行编码，并将编码后的字节后写入到输出流
* 当发生下溢时，可能会抛异常(遇到了有缺陷的输入)
*/
flushLeftoverChar(null, true);
try {
for(; ; ) {
// 刷新内部缓冲区
CoderResult cr = encoder.flush(bb);
if(cr.isUnderflow()) {
break;
}
if(cr.isOverflow()) {
assert bb.position()>0;
// 将内部缓冲区中的字节写到最终输出流中
writeBytes();
continue;
}
cr.throwException();
}
if(bb.position()>0) {
// 将内部缓冲区中的字节写到最终输出流中
writeBytes();
}
if(ch != null) {
ch.close();
} else {
out.close();
}
} catch(IOException x) {
encoder.reset();
throw x;
}
}
/*
* 对上一轮写入中残留下的那个字符进行编码，并将编码后的字节后写入到输出流
*
* 如果之前有残留的字符，则需要从cb中再多读一个字符以配合编码，如果此时cb中已经没有可读字符，则该字符继续被残留。
* 如果之前没有残留的字符，则需要从cb中读取一个或读取两个字符进行编码
*
* endOfInput=true ：当发生下溢时，可能会抛异常(遇到了有缺陷的输入)
* endOfInput=false：当发生下溢时，不会抛异常，因为可以期待后续的输入
*/
private void flushLeftoverChar(CharBuffer cb, boolean endOfInput) throws IOException {
// 之前没有残留未处理字符，且不需要关闭输入流
if(!haveLeftoverChar && !endOfInput) {
return;
}
/* 至此，说明之前残留待处理字符，或(且)需要立即关闭输入流 */
if(lcb == null) {
/*
* 构造非直接缓冲区HeapCharBuffer：将缓冲区建立在JVM的内存中
* 这里容量分配为2的原因是现存的任何符号，最多用两个char就可以表示了
*/
lcb = CharBuffer.allocate(2);
} else {
// 如果不为空，先清空它
lcb.clear();
}
if(haveLeftoverChar) {
// 向lcb中存入之前缓存的一个待读字符
lcb.put(leftoverChar);
}
// 如果cb中仍有可读的字符
if((cb != null) && cb.hasRemaining()) {
// 继续从cb中读取一个char存入lcb
lcb.put(cb.get());
}
// 将lcb从写模式转为读模式
lcb.flip();
// 如果lcb中还有待读字符，或者中断了输入
while(lcb.hasRemaining() || endOfInput) {
/*
* 从给定的输入缓冲区lcb中编码尽可能多的字符，将结果写入给定的输出缓冲区bb。
*
* endOfInput=true表示当发生下溢时，输入立即结束，即不会再提供更多输入
* endOfInput=false表示当发生下溢时，可能还会有后续的输入
*/
CoderResult cr = encoder.encode(lcb, bb, endOfInput);
/*
* 发生下溢，输出缓冲区仍有空闲
*
* 可能是lcb进来时有2个char，但是都被处理完了，那么后续就break了
* 可能是lcb进来时有1个char，但这个char来自cb，此时需要如果ch处理完了，直接return，如果cb没处理完，则尝试从cb中再读一个char进来处理
* 可能是lcb进来时有1个char，但这个char来自leftoverChar，此时cb已处理完，则leftoverChar重新记下该char，并且return
*/
if(cr.isUnderflow()) {
// 如果lcb中还有待读字符
if(lcb.hasRemaining()) {
// 将lcb中剩下未处理的那个char缓存到leftoverChar中
leftoverChar = lcb.get();
// 如果cb中仍有可读的字符
if(cb != null && cb.hasRemaining()) {
// 清空，进入写模式
lcb.clear();
// 重复向lcb填充2个char，填充完成后切换到读模式
lcb.put(leftoverChar).put(cb.get()).flip();
continue;
}
return;
}
break;
}
// 发生上溢，输出缓冲区已经满了
if(cr.isOverflow()) {
assert bb.position()>0;
// 将内部缓冲区中的字节写到最终输出流中
writeBytes();
continue;
}
cr.throwException();
}
haveLeftoverChar = false;
}
// 将内部缓冲区中的字节写到最终输出流中
private void writeBytes() throws IOException {
bb.flip(); // 将内部缓冲区从写模式切换到读模式
int lim = bb.limit();
int pos = bb.position();
assert (pos<=lim);
int rem = (pos<=lim ? lim - pos : 0);
if(rem>0) {
if(ch != null) {
assert ch.write(bb) == rem : rem;
} else {
// 返回该buffer内部的数组
byte[] b = bb.array();
int off = bb.arrayOffset() + pos;
// 将字节数组b中off处起的rem个字节写入到输出流
out.write(b, off, rem);
}
}
// 清理缓冲区，重置标记
bb.clear();
}
// 返回字节编码器使用的字符集名称
String encodingName() {
return ((cs instanceof HistoricallyNamedCharset) ? ((HistoricallyNamedCharset) cs).historicalName() : cs.name());
}
// 判断输出流编码器是否处于开启状态
private boolean isOpen() {
return !closed;
}
// 确保输出流编码器处于开启状态
private void ensureOpen() throws IOException {
if(closed) {
throw new IOException("Stream closed");
}
}
}
2237
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
