/*
* Copyright 2012 The Netty Project
*
* The Netty Project licenses this file to you under the Apache License,
* version 2.0 (the "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*/
package io.netty.handler.codec.http;
import io.netty.buffer.ByteBuf;
import io.netty.buffer.ByteBufUtil;
import io.netty.buffer.Unpooled;
import io.netty.channel.ChannelHandlerContext;
import io.netty.channel.FileRegion;
import io.netty.handler.codec.MessageToMessageEncoder;
import io.netty.util.CharsetUtil;
import io.netty.util.internal.StringUtil;
import java.util.Iterator;
import java.util.List;
import java.util.Map.Entry;
import static io.netty.buffer.Unpooled.directBuffer;
import static io.netty.buffer.Unpooled.unreleasableBuffer;
import static io.netty.handler.codec.http.HttpConstants.CR;
import static io.netty.handler.codec.http.HttpConstants.LF;
/**
* Encodes an {@link HttpMessage} or an {@link HttpContent} into
* a {@link ByteBuf}.
*
* <h3>Extensibility</h3>
*
* Please note that this encoder is designed to be extended to implement
* a protocol derived from HTTP, such as
* <a href="http://en.wikipedia.org/wiki/Real_Time_Streaming_Protocol">RTSP</a> and
* <a href="http://en.wikipedia.org/wiki/Internet_Content_Adaptation_Protocol">ICAP</a>.
* To implement the encoder of such a derived protocol, extend this class and
* implement all abstract methods properly.
*/
public abstract class HttpObjectEncoder<H extends HttpMessage> extends MessageToMessageEncoder<Object> {
static final int CRLF_SHORT = (CR << 8) | LF; //十進制爲3338 二進制爲0xOD 0xOA ascii碼爲\r\n
private static final int ZERO_CRLF_MEDIUM = ('0' << 16) | CRLF_SHORT;
private static final byte[] ZERO_CRLF_CRLF = { '0', CR, LF, CR, LF };
private static final ByteBuf CRLF_BUF = unreleasableBuffer(directBuffer(2).writeByte(CR).writeByte(LF));
private static final ByteBuf ZERO_CRLF_CRLF_BUF = unreleasableBuffer(directBuffer(ZERO_CRLF_CRLF.length)
.writeBytes(ZERO_CRLF_CRLF));
private static final float HEADERS_WEIGHT_NEW = 1 / 5f;
private static final float HEADERS_WEIGHT_HISTORICAL = 1 - HEADERS_WEIGHT_NEW;
private static final float TRAILERS_WEIGHT_NEW = HEADERS_WEIGHT_NEW;
private static final float TRAILERS_WEIGHT_HISTORICAL = HEADERS_WEIGHT_HISTORICAL;
private static final int ST_INIT = 0;
private static final int ST_CONTENT_NON_CHUNK = 1;
private static final int ST_CONTENT_CHUNK = 2;
private static final int ST_CONTENT_ALWAYS_EMPTY = 3;
@SuppressWarnings("RedundantFieldInitialization")
private int state = ST_INIT;
/**
* Used to calculate an exponential moving average of the encoded size of the initial line and the headers for
* a guess for future buffer allocations.
*/
private float headersEncodedSizeAccumulator = 256;
/**
* Used to calculate an exponential moving average of the encoded size of the trailers for
* a guess for future buffer allocations.
*/
private float trailersEncodedSizeAccumulator = 256;
@Override
protected void encode(ChannelHandlerContext ctx, Object msg, List<Object> out) throws Exception {
ByteBuf buf = null;
if (msg instanceof HttpMessage) {
if (state != ST_INIT) {
throw new IllegalStateException("unexpected message type: " + StringUtil.simpleClassName(msg)
+ ", state: " + state);
}
@SuppressWarnings({ "unchecked", "CastConflictsWithInstanceof" })
H m = (H) msg;
buf = ctx.alloc().buffer((int) headersEncodedSizeAccumulator);
// Encode the message.
//編碼Http響應頭第一行 HTTP/1.1 200 OK \r\n
encodeInitialLine(buf, m);
//判斷響應體類型, ST_CONTENT_ALWAYS_EMPTY=沒有響應體
//ST_CONTENT_CHUNK 塊transfer-encoding響應方式
//ST_CONTENT_NON_CHUNK 非塊的響應體方式
state = isContentAlwaysEmpty(m) ? ST_CONTENT_ALWAYS_EMPTY :
HttpUtil.isTransferEncodingChunked(m) ? ST_CONTENT_CHUNK : ST_CONTENT_NON_CHUNK;
//按照Http協議規定,根據響應碼設置對應的Http頭信息
sanitizeHeadersBeforeEncode(m, state == ST_CONTENT_ALWAYS_EMPTY);
//編碼Http響應頭, 按照Http規範,把頭信息輸出到buf中,例如:
//content-type: text/html; charset=UTF-8 \r\n
//content-length: 7 \r\n
encodeHeaders(m.headers(), buf);
//最後要加入\r\b符 表示頭信息結束
//content-type: text/html; charset=UTF-8 \r\n
//content-length: 7 \r\n
//\r\n 這裏表示結束
//這裏表示http響應體的數據(用倆個回車換行分隔開)
ByteBufUtil.writeShortBE(buf, CRLF_SHORT);
headersEncodedSizeAccumulator = HEADERS_WEIGHT_NEW * padSizeForAccumulation(buf.readableBytes()) +
HEADERS_WEIGHT_HISTORICAL * headersEncodedSizeAccumulator;
}
// Bypass the encoder in case of an empty buffer, so that the following idiom works:
//
// ch.write(Unpooled.EMPTY_BUFFER).addListener(ChannelFutureListener.CLOSE);
//
// See https://github.com/netty/netty/issues/2983 for more information.
if (msg instanceof ByteBuf) {
final ByteBuf potentialEmptyBuf = (ByteBuf) msg;
if (!potentialEmptyBuf.isReadable()) {
out.add(potentialEmptyBuf.retain());
return;
}
}
//處理Http響應體
if (msg instanceof HttpContent || msg instanceof ByteBuf || msg instanceof FileRegion) {
switch (state) {
case ST_INIT:
throw new IllegalStateException("unexpected message type: " + StringUtil.simpleClassName(msg));
case ST_CONTENT_NON_CHUNK: //不是塊數據流,那就屬於定長的。
//計算長度
final long contentLength = contentLength(msg);
if (contentLength > 0) {
//如果buf還有空間容納響應體的字節數量
if (buf != null && buf.writableBytes() >= contentLength && msg instanceof HttpContent) {
// merge into other buffer for performance reasons
//把響應體的字節寫入到buf中返回
buf.writeBytes(((HttpContent) msg).content());
out.add(buf);
} else {
//輸出buf,這裏的buf沒包含響應體
if (buf != null) {
out.add(buf);
}
//retain一下在輸出,因爲msg會被父類釋放一次
out.add(encodeAndRetain(msg));
}
//如果是最後一個響應體,則標記重新開始狀態
if (msg instanceof LastHttpContent) {
state = ST_INIT;
}
break;
}
// fall-through!
case ST_CONTENT_ALWAYS_EMPTY:
//輸出響應頭
if (buf != null) {
// We allocated a buffer so add it now.
out.add(buf);
} else {
// Need to produce some output otherwise an
// IllegalStateException will be thrown as we did not write anything
// Its ok to just write an EMPTY_BUFFER as if there are reference count issues these will be
// propagated as the caller of the encode(...) method will release the original
// buffer.
// Writing an empty buffer will not actually write anything on the wire, so if there is a user
// error with msg it will not be visible externally
out.add(Unpooled.EMPTY_BUFFER);
}
break;
//按塊方式輸出
case ST_CONTENT_CHUNK:
if (buf != null) {
// We allocated a buffer so add it now.
//輸出響應頭
out.add(buf);
}
encodeChunkedContent(ctx, msg, contentLength(msg), out);
break;
default:
throw new Error();
}
if (msg instanceof LastHttpContent) {
state = ST_INIT;
}
} else if (buf != null) {
out.add(buf);
}
}
/**
* Encode the {@link HttpHeaders} into a {@link ByteBuf}.
*/
protected void encodeHeaders(HttpHeaders headers, ByteBuf buf) {
Iterator<Entry<CharSequence, CharSequence>> iter = headers.iteratorCharSequence();
while (iter.hasNext()) {
Entry<CharSequence, CharSequence> header = iter.next();
HttpHeadersEncoder.encoderHeader(header.getKey(), header.getValue(), buf);
}
}
private void encodeChunkedContent(ChannelHandlerContext ctx, Object msg, long contentLength, List<Object> out) {
//有數據的情況就按塊方式發送
if (contentLength > 0) {
//把長度編碼爲Hex格式
String lengthHex = Long.toHexString(contentLength);
//長度+2分配ByteBuf
ByteBuf buf = ctx.alloc().buffer(lengthHex.length() + 2);
//輸出長度
buf.writeCharSequence(lengthHex, CharsetUtil.US_ASCII);
//輸出\r\n
ByteBufUtil.writeShortBE(buf, CRLF_SHORT);
out.add(buf); //輸出塊的長度信息比如 14(十進制是20)\r\n
out.add(encodeAndRetain(msg)); //輸出消息二進制
out.add(CRLF_BUF.duplicate()); //後面跟着\r\n表示塊結束
}
//最後一個數據塊
if (msg instanceof LastHttpContent) {
HttpHeaders headers = ((LastHttpContent) msg).trailingHeaders();
if (headers.isEmpty()) {
//發送塊結束標記 0\r\n\r\n
out.add(ZERO_CRLF_CRLF_BUF.duplicate());
} else {
ByteBuf buf = ctx.alloc().buffer((int) trailersEncodedSizeAccumulator);
//寫入發送塊結束標記 0\r\n\r\n
ByteBufUtil.writeMediumBE(buf, ZERO_CRLF_MEDIUM);
//額外的頭信息
encodeHeaders(headers, buf);
//寫入結束標記
ByteBufUtil.writeShortBE(buf, CRLF_SHORT);
trailersEncodedSizeAccumulator = TRAILERS_WEIGHT_NEW * padSizeForAccumulation(buf.readableBytes()) +
TRAILERS_WEIGHT_HISTORICAL * trailersEncodedSizeAccumulator;
out.add(buf);
}
} else if (contentLength == 0) {
// Need to produce some output otherwise an
// IllegalStateException will be thrown
out.add(encodeAndRetain(msg));
}
}
/**
* Allows to sanitize headers of the message before encoding these.
*/
protected void sanitizeHeadersBeforeEncode(@SuppressWarnings("unused") H msg, boolean isAlwaysEmpty) {
// noop
}
/**
* Determine whether a message has a content or not. Some message may have headers indicating
* a content without having an actual content, e.g the response to an HEAD or CONNECT request.
*
* @param msg the message to test
* @return {@code true} to signal the message has no content
*/
protected boolean isContentAlwaysEmpty(@SuppressWarnings("unused") H msg) {
return false;
}
@Override
public boolean acceptOutboundMessage(Object msg) throws Exception {
return msg instanceof HttpObject || msg instanceof ByteBuf || msg instanceof FileRegion;
}
private static Object encodeAndRetain(Object msg) {
if (msg instanceof ByteBuf) {
return ((ByteBuf) msg).retain();
}
if (msg instanceof HttpContent) {
return ((HttpContent) msg).content().retain();
}
if (msg instanceof FileRegion) {
return ((FileRegion) msg).retain();
}
throw new IllegalStateException("unexpected message type: " + StringUtil.simpleClassName(msg));
}
private static long contentLength(Object msg) {
if (msg instanceof HttpContent) {
return ((HttpContent) msg).content().readableBytes();
}
if (msg instanceof ByteBuf) {
return ((ByteBuf) msg).readableBytes();
}
if (msg instanceof FileRegion) {
return ((FileRegion) msg).count();
}
throw new IllegalStateException("unexpected message type: " + StringUtil.simpleClassName(msg));
}
/**
* Add some additional overhead to the buffer. The rational is that it is better to slightly over allocate and waste
* some memory, rather than under allocate and require a resize/copy.
* @param readableBytes The readable bytes in the buffer.
* @return The {@code readableBytes} with some additional padding.
*/
private static int padSizeForAccumulation(int readableBytes) {
return (readableBytes << 2) / 3;
}
@Deprecated
protected static void encodeAscii(String s, ByteBuf buf) {
buf.writeCharSequence(s, CharsetUtil.US_ASCII);
}
protected abstract void encodeInitialLine(ByteBuf buf, H message) throws Exception;
}