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.header; 014 015import java.net.*; 016import java.util.function.*; 017 018import org.apache.juneau.http.annotation.*; 019 020/** 021 * Represents a parsed <l>Referer</l> HTTP request header. 022 * 023 * <p> 024 * This is the address of the previous web page from which a link to the currently requested page was followed. 025 * (The word “referrer” has been misspelled in the RFC as well as in most implementations to the point that it has 026 * become standard usage and is considered correct terminology) 027 * 028 * <h5 class='figure'>Example</h5> 029 * <p class='bcode'> 030 * Referer: http://en.wikipedia.org/wiki/Main_Page 031 * </p> 032 * 033 * <h5 class='topic'>RFC2616 Specification</h5> 034 * 035 * The Referer[sic] request-header field allows the client to specify, for the server's benefit, the address (URI) of 036 * the resource from which the Request-URI was obtained (the "referrer", although the header field is misspelled.) 037 * The Referer request-header allows a server to generate lists of back-links to resources for interest, logging, 038 * optimized caching, etc. 039 * It also allows obsolete or mistyped links to be traced for maintenance. 040 * The Referer field MUST NOT be sent if the Request-URI was obtained from a source that does not have its own URI, 041 * such as input from the user keyboard. 042 * 043 * <p class='bcode'> 044 * Referer = "Referer" ":" ( absoluteURI | relativeURI ) 045 * </p> 046 * 047 * <p> 048 * Example: 049 * <p class='bcode'> 050 * Referer: http://www.w3.org/hypertext/DataSources/Overview.html 051 * </p> 052 * 053 * <p> 054 * If the field value is a relative URI, it SHOULD be interpreted relative to the Request-URI. 055 * The URI MUST NOT include a fragment. See section 15.1.3 for security considerations. 056 * 057 * <h5 class='section'>See Also:</h5><ul> 058 * <li class='link'><a class="doclink" href="../../../../../index.html#juneau-rest-common">juneau-rest-common</a> 059 * <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a> 060 * </ul> 061 * 062 * @serial exclude 063 */ 064@Header("Referer") 065public class Referer extends BasicUriHeader { 066 067 //----------------------------------------------------------------------------------------------------------------- 068 // Static 069 //----------------------------------------------------------------------------------------------------------------- 070 071 private static final long serialVersionUID = 1L; 072 private static final String NAME = "Referer"; 073 074 /** 075 * Static creator. 076 * 077 * @param value 078 * The header value. 079 * <br>Must be parsable by {@link URI#create(String)}. 080 * <br>Can be <jk>null</jk>. 081 * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>. 082 */ 083 public static Referer of(String value) { 084 return value == null ? null : new Referer(value); 085 } 086 087 /** 088 * Static creator. 089 * 090 * @param value 091 * The header value. 092 * <br>Can be <jk>null</jk>. 093 * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>. 094 */ 095 public static Referer of(URI value) { 096 return value == null ? null : new Referer(value); 097 } 098 099 /** 100 * Static creator with delayed value. 101 * 102 * <p> 103 * Header value is re-evaluated on each call to {@link #getValue()}. 104 * 105 * @param value 106 * The supplier of the header value. 107 * <br>Can be <jk>null</jk>. 108 * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>. 109 */ 110 public static Referer of(Supplier<URI> value) { 111 return value == null ? null : new Referer(value); 112 } 113 114 //----------------------------------------------------------------------------------------------------------------- 115 // Instance 116 //----------------------------------------------------------------------------------------------------------------- 117 118 /** 119 * Constructor. 120 * 121 * @param value 122 * The header value. 123 * <br>Must be parsable by {@link URI#create(String)}. 124 * <br>Can be <jk>null</jk>. 125 */ 126 public Referer(String value) { 127 super(NAME, value); 128 } 129 130 /** 131 * Constructor. 132 * 133 * @param value 134 * The header value. 135 * <br>Can be <jk>null</jk>. 136 */ 137 public Referer(URI value) { 138 super(NAME, value); 139 } 140 141 /** 142 * Constructor with delayed value. 143 * 144 * <p> 145 * Header value is re-evaluated on each call to {@link #getValue()}. 146 * 147 * @param value 148 * The supplier of the header value. 149 * <br>Can be <jk>null</jk>. 150 */ 151 public Referer(Supplier<URI> value) { 152 super(NAME, value); 153 } 154}