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.util.function.*;
020
021import org.apache.juneau.http.annotation.*;
022
023/**
024 * Represents a parsed <l>Vary</l> HTTP response header.
025 *
026 * <p>
027 * Tells downstream proxies how to match future request headers to decide whether the cached response can be used rather
028 * than requesting a fresh one from the origin server.
029 *
030 * <h5 class='figure'>Example</h5>
031 * <p class='bcode'>
032 *    Vary: *
033 *    Vary: Accept-Language
034 * </p>
035 *
036 * <h5 class='topic'>RFC2616 Specification</h5>
037 *
038 * The Vary field value indicates the set of request-header fields that fully determines, while the response is fresh,
039 * whether a cache is permitted to use the response to reply to a subsequent request without revalidation.
040 * For uncacheable or stale responses, the Vary field value advises the user agent about the criteria that were used to
041 * select the representation.
042 * A Vary field value of "*" implies that a cache cannot determine from the request headers of a subsequent request
043 * whether this response is the appropriate representation.
044 * See section 13.6 for use of the Vary header field by caches.
045 * <p class='bcode'>
046 *    Vary  = "Vary" ":" ( "*" | 1#field-name )
047 * </p>
048 *
049 * <p>
050 * An HTTP/1.1 server SHOULD include a Vary header field with any cacheable response that is subject to server-driven
051 * negotiation.
052 * Doing so allows a cache to properly interpret future requests on that resource and informs the user agent about the
053 * presence of negotiation on that resource.
054 * A server MAY include a Vary header field with a non-cacheable response that is subject to server-driven negotiation,
055 * since this might provide the user agent with useful information about the dimensions over which the response varies
056 * at the time of the response.
057 *
058 * <p>
059 * A Vary field value consisting of a list of field-names signals that the representation selected for the response is
060 * based on a selection algorithm which considers ONLY the listed request-header field values in selecting the most
061 * appropriate representation.
062 * A cache MAY assume that the same selection will be made for future requests with the same values for the listed
063 * field names, for the duration of time for which the response is fresh.
064 *
065 * <p>
066 * The field-names given are not limited to the set of standard request-header fields defined by this specification.
067 * Field names are case-insensitive.
068 *
069 * <p>
070 * A Vary field value of "*" signals that unspecified parameters not limited to the request-headers (e.g., the network
071 * address of the client), play a role in the selection of the response representation.
072 * The "*" value MUST NOT be generated by a proxy server; it may only be generated by an origin server.
073 *
074 * <h5 class='section'>See Also:</h5><ul>
075 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommonBasics">juneau-rest-common Basics</a>
076 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
077 * </ul>
078 *
079 * @serial exclude
080 */
081@Header("Vary")
082public class Vary extends BasicStringHeader {
083   private static final long serialVersionUID = 1L;
084   private static final String NAME = "Vary";
085
086   /**
087    * Static creator.
088    *
089    * @param value
090    *    The header value.
091    *    <br>Can be <jk>null</jk>.
092    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
093    */
094   public static Vary of(String value) {
095      return value == null ? null : new Vary(value);
096   }
097
098   /**
099    * Static creator with delayed value.
100    *
101    * <p>
102    * Header value is re-evaluated on each call to {@link #getValue()}.
103    *
104    * @param value
105    *    The supplier of 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 Vary of(Supplier<String> value) {
110      return value == null ? null : new Vary(value);
111   }
112
113   /**
114    * Constructor.
115    *
116    * @param value
117    *    The header value.
118    *    <br>Can be <jk>null</jk>.
119    */
120   public Vary(String value) {
121      super(NAME, value);
122   }
123
124   /**
125    * Constructor with delayed value.
126    *
127    * <p>
128    * Header value is re-evaluated on each call to {@link #getValue()}.
129    *
130    * @param value
131    *    The supplier of the header value.
132    *    <br>Can be <jk>null</jk>.
133    */
134   public Vary(Supplier<String> value) {
135      super(NAME, value);
136   }
137}