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   private static final long serialVersionUID = 1L;
071   private static final String NAME = "Referer";
072
073   /**
074    * Static creator.
075    *
076    * @param value
077    *    The header value.
078    *    <br>Must be parsable by {@link URI#create(String)}.
079    *    <br>Can be <jk>null</jk>.
080    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
081    */
082   public static Referer of(String value) {
083      return value == null ? null : new Referer(value);
084   }
085
086   /**
087    * Static creator with delayed value.
088    *
089    * <p>
090    * Header value is re-evaluated on each call to {@link #getValue()}.
091    *
092    * @param value
093    *    The supplier of the header value.
094    *    <br>Can be <jk>null</jk>.
095    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
096    */
097   public static Referer of(Supplier<URI> value) {
098      return value == null ? null : new Referer(value);
099   }
100
101   /**
102    * Static creator.
103    *
104    * @param value
105    *    The header value.
106    *    <br>Can be <jk>null</jk>.
107    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
108    */
109   public static Referer of(URI value) {
110      return value == null ? null : new Referer(value);
111   }
112
113   /**
114    * Constructor.
115    *
116    * @param value
117    *    The header value.
118    *    <br>Must be parsable by {@link URI#create(String)}.
119    *    <br>Can be <jk>null</jk>.
120    */
121   public Referer(String value) {
122      super(NAME, value);
123   }
124
125   /**
126    * Constructor with delayed value.
127    *
128    * <p>
129    * Header value is re-evaluated on each call to {@link #getValue()}.
130    *
131    * @param value
132    *    The supplier of the header value.
133    *    <br>Can be <jk>null</jk>.
134    */
135   public Referer(Supplier<URI> value) {
136      super(NAME, value);
137   }
138
139   /**
140    * Constructor.
141    *
142    * @param value
143    *    The header value.
144    *    <br>Can be <jk>null</jk>.
145    */
146   public Referer(URI value) {
147      super(NAME, value);
148   }
149}