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