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