001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.http.classic.header; 018 019import java.util.function.*; 020 021import org.apache.juneau.http.*; 022 023/** 024 * Represents a parsed <l>Via</l> HTTP response header. 025 * 026 * <p> 027 * Informs the client of proxies through which the response was sent. 028 * 029 * <h2 class='figure'>Example</h2> 030 * <p class='bcode'> 031 * Via: 1.0 fred, 1.1 example.com (Apache/1.1) 032 * </p> 033 * 034 * <p> 035 * Informs the client of proxies through which the response was sent. 036 * 037 * <h2 class='figure'>Example</h2> 038 * <p class='bcode'> 039 * Via: 1.0 fred, 1.1 example.com (Apache/1.1) 040 * </p> 041 * 042 * <h2 class='topic'>RFC2616 Specification</h2> 043 * 044 * The Via general-header field MUST be used by gateways and proxies to indicate the intermediate protocols and 045 * recipients between the user agent and the server on requests, and between the origin server and the client on 046 * responses. 047 * It is analogous to the "Received" field of RFC 822 and is intended to be used for tracking message forwards, 048 * avoiding request loops, and identifying the protocol capabilities of all senders along the request/response chain. 049 * 050 * <p class='bcode'> 051 * Via = "Via" ":" 1#( received-protocol received-by [ comment ] ) 052 * received-protocol = [ protocol-name "/" ] protocol-version 053 * protocol-name = token 054 * protocol-version = token 055 * received-by = ( host [ ":" port ] ) | pseudonym 056 * pseudonym = token 057 * </p> 058 * 059 * <p> 060 * The received-protocol indicates the protocol version of the message received by the server or client along each 061 * segment of the request/response chain. 062 * The received-protocol version is appended to the Via field value when the message is forwarded so that information 063 * about the protocol capabilities of upstream applications remains visible to all recipients. 064 * 065 * <p> 066 * The protocol-name is optional if and only if it would be "HTTP". 067 * The received-by field is normally the host and optional port number of a recipient server or client that subsequently 068 * forwarded the message. 069 * However, if the real host is considered to be sensitive information, it MAY be replaced by a pseudonym. 070 * If the port is not given, it MAY be assumed to be the default port of the received-protocol. 071 * 072 * <p> 073 * Multiple Via field values represents each proxy or gateway that has forwarded the message. 074 * Each recipient MUST append its information such that the end result is ordered according to the sequence of 075 * forwarding applications. 076 * 077 * <p> 078 * Comments MAY be used in the Via header field to identify the software of the recipient proxy or gateway, analogous 079 * to the User-Agent and Server header fields. 080 * However, all comments in the Via field are optional and MAY be removed by any recipient prior to forwarding the 081 * message. 082 * 083 * <p> 084 * For example, a request message could be sent from an HTTP/1.0 user agent to an internal proxy code-named "fred", 085 * which uses HTTP/1.1 to forward the request to a public proxy at nowhere.com, which completes the request by 086 * forwarding it to the origin server at www.ics.uci.edu. 087 * The request received by www.ics.uci.edu would then have the following Via header field: 088 * <p class='bcode'> 089 * Via: 1.0 fred, 1.1 nowhere.com (Apache/1.1) 090 * </p> 091 * 092 * <p> 093 * Proxies and gateways used as a portal through a network firewall SHOULD NOT, by default, forward the names and ports 094 * of hosts within the firewall region. 095 * This information SHOULD only be propagated if explicitly enabled. 096 * If not enabled, the received-by host of any host behind the firewall SHOULD be replaced by an appropriate pseudonym 097 * for that host. 098 * 099 * <p> 100 * For organizations that have strong privacy requirements for hiding internal structures, a proxy MAY combine an 101 * ordered subsequence of Via header field entries with identical received-protocol values into a single such entry. 102 * For example... 103 * <p class='bcode'> 104 * Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy 105 * </p> 106 * 107 * <p> 108 * ...could be collapsed to... 109 * <p class='bcode'> 110 * Via: 1.0 ricky, 1.1 mertz, 1.0 lucy 111 * </p> 112 * 113 * <p> 114 * Applications SHOULD NOT combine multiple entries unless they are all under the same organizational control and the 115 * hosts have already been replaced by pseudonyms. 116 * Applications MUST NOT combine entries which have different received-protocol values. 117 * 118 * <h2 class='section'>See Also:</h2><ul> 119 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommon">juneau-rest-common</a> 120 * <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a> 121 * </ul> 122 * 123 * @serial exclude 124 */ 125@Header("Via") 126@SuppressWarnings({ 127 "java:S9149" // Public Juneau DSL factory; hiding parent of()/create() is intentional. 128}) 129public class Via extends BasicCsvHeader { 130 private static final long serialVersionUID = 1L; 131 private static final String NAME = "Via"; 132 133 /** 134 * Static creator. 135 * 136 * @param value 137 * The header value. 138 * <br>Can be <jk>null</jk>. 139 * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>. 140 */ 141 public static Via of(String value) { 142 return value == null ? null : new Via(value); 143 } 144 145 /** 146 * Static creator. 147 * 148 * @param value 149 * The header value. 150 * <br>Can be <jk>null</jk>. 151 * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>. 152 */ 153 public static Via of(String...value) { 154 return value == null ? null : new Via(value); 155 } 156 157 /** 158 * Static creator for two CSV tokens. 159 * 160 * <p> 161 * This distinct fixed-arity overload ensures two literal {@link String} arguments resolve to this class's own 162 * factory (returning a {@link Via}) rather than the inherited fixed-arity {@link BasicCsvHeader#of(String,String)}, 163 * which Java overload resolution would otherwise prefer. 164 * 165 * @param value1 The first CSV token. 166 * @param value2 The second CSV token. 167 * @return A new header bean. 168 */ 169 public static Via of(String value1, String value2) { 170 return new Via(value1, value2); 171 } 172 173 /** 174 * Static creator with delayed value. 175 * 176 * <p> 177 * Header value is re-evaluated on each call to {@link #getValue()}. 178 * 179 * @param value 180 * The supplier of the header value. 181 * <br>Can be <jk>null</jk>. 182 * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>. 183 */ 184 public static Via of(Supplier<String[]> value) { 185 return value == null ? null : new Via(value); 186 } 187 188 /** 189 * Constructor. 190 * 191 * @param value 192 * The header value. 193 * <br>Can be <jk>null</jk> to create a header with no value. 194 */ 195 public Via(String value) { 196 super(NAME, value); 197 } 198 199 /** 200 * Constructor. 201 * 202 * @param value 203 * The header value. 204 * <br>Can be <jk>null</jk> or empty to create a header with no value. 205 */ 206 public Via(String...value) { 207 super(NAME, value); 208 } 209 210 /** 211 * Constructor with delayed value. 212 * 213 * <p> 214 * Header value is re-evaluated on each call to {@link #getValue()}. 215 * 216 * @param value 217 * The supplier of the header value. 218 * <br>Can be <jk>null</jk> to create a header with no value. 219 */ 220 public Via(Supplier<String[]> value) { 221 super(NAME, value); 222 } 223}