001// *************************************************************************************************************************** 002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * 003// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * 004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance * 005// * with the License. You may obtain a copy of the License at * 006// * * 007// * http://www.apache.org/licenses/LICENSE-2.0 * 008// * * 009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * 010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * 011// * specific language governing permissions and limitations under the License. * 012// *************************************************************************************************************************** 013package org.apache.juneau.http; 014 015import static org.apache.juneau.http.Constants.*; 016 017import org.apache.juneau.http.annotation.*; 018import org.apache.juneau.internal.*; 019 020/** 021 * Represents a parsed <l>TE</l> HTTP request header. 022 * 023 * <p> 024 * The transfer encodings the user agent is willing to accept: the same values as for the response header field 025 * Transfer-Encoding can be used, plus the "trailers" value (related to the "chunked" transfer method) to notify the 026 * server it expects to receive additional fields in the trailer after the last, zero-sized, chunk. 027 * 028 * <h5 class='figure'>Example</h5> 029 * <p class='bcode w800'> 030 * TE: trailers, deflate 031 * </p> 032 * 033 * <h5 class='topic'>RFC2616 Specification</h5> 034 * 035 * The TE request-header field indicates what extension transfer-codings it is willing to accept in the response and 036 * whether or not it is willing to accept trailer fields in a chunked transfer-coding. 037 * Its value may consist of the keyword "trailers" and/or a comma-separated list of extension transfer-coding names 038 * with optional accept parameters (as described in section 3.6). 039 * 040 * <p class='bcode w800'> 041 * TE = "TE" ":" #( t-codings ) 042 * t-codings = "trailers" | ( transfer-extension [ accept-params ] ) 043 * </p> 044 * 045 * <p> 046 * The presence of the keyword "trailers" indicates that the client is willing to accept trailer fields in a chunked 047 * transfer-coding, as defined in section 3.6.1. 048 * This keyword is reserved for use with transfer-coding values even though it does not itself represent a 049 * transfer-coding. 050 * 051 * <p> 052 * Examples of its use are: 053 * <p class='bcode w800'> 054 * TE: deflate 055 * TE: 056 * TE: trailers, deflate;q=0.5 057 * </p> 058 * 059 * <p> 060 * The TE header field only applies to the immediate connection. 061 * Therefore, the keyword MUST be supplied within a Connection header field (section 14.10) whenever TE is present in 062 * an HTTP/1.1 message. 063 * 064 * <p> 065 * A server tests whether a transfer-coding is acceptable, according to a TE field, using these rules: 066 * <ol> 067 * <li>The "chunked" transfer-coding is always acceptable. 068 * If the keyword "trailers" is listed, the client indicates that it is willing to accept trailer fields in the 069 * chunked response on behalf of itself and any downstream clients. 070 * The implication is that, if given, the client is stating that either all downstream clients are willing to accept 071 * trailer fields in the forwarded response, or that it will attempt to buffer the response on behalf of downstream 072 * recipients. 073 * Note: HTTP/1.1 does not define any means to limit the size of a chunked response such that a client can be assured 074 * of buffering the entire response. 075 * <li>If the transfer-coding being tested is one of the transfer-codings listed in the TE field, then it is acceptable 076 * unless it is accompanied by a qvalue of 0. (As defined in section 3.9, a qvalue of 0 means "not acceptable.") 077 * <li>If multiple transfer-codings are acceptable, then the acceptable transfer-coding with the highest non-zero 078 * qvalue is preferred. 079 * The "chunked" transfer-coding always has a qvalue of 1. 080 * </ol> 081 * 082 * <p> 083 * If the TE field-value is empty or if no TE field is present, the only transfer-coding is "chunked". 084 * A message with no transfer-coding is always acceptable. 085 * 086 * <h5 class='section'>See Also:</h5> 087 * <ul class='doctree'> 088 * <li class='extlink'>{@doc RFC2616} 089 * </ul> 090 */ 091@Header("TE") 092public final class TE extends HeaderRangeArray { 093 094 private static final Cache<String,TE> cache = new Cache<>(NOCACHE, CACHE_MAX_SIZE); 095 096 /** 097 * Returns a parsed <code>TE</code> header. 098 * 099 * @param value The <code>TE</code> header string. 100 * @return The parsed <code>TE</code> header, or <jk>null</jk> if the string was null. 101 */ 102 public static TE forString(String value) { 103 if (value == null) 104 return null; 105 TE te = cache.get(value); 106 if (te == null) 107 te = cache.put(value, new TE(value)); 108 return te; 109 } 110 111 private TE(String value) { 112 super(value); 113 } 114}