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}