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>Cache-Control</l> HTTP request header.
025 *
026 * <p>
027 * Used to specify directives that must be obeyed by all caching mechanisms along the request-response chain.
028 *
029 * <h5 class='figure'>Example</h5>
030 * <p class='bcode'>
031 *    Cache-Control: no-cache
032 * </p>
033 *
034 * <h5 class='topic'>RFC2616 Specification</h5>
035 *
036 * The Cache-Control general-header field is used to specify directives that MUST be obeyed by all caching mechanisms
037 * along the request/response chain.
038 * The directives specify behavior intended to prevent caches from adversely interfering with the request or response.
039 * These directives typically override the default caching algorithms.
040 * Cache directives are unidirectional in that the presence of a directive in a request does not imply that the same
041 * directive is to be given in the response.
042 *
043 * <p>
044 * Note that HTTP/1.0 caches might not implement Cache-Control and might only implement Pragma: no-cache (see section
045 * 14.32).
046 *
047 * <p>
048 * Cache directives MUST be passed through by a proxy or gateway application, regardless of their significance to that
049 * application, since the directives might be applicable to all recipients along the request/response chain.
050 * It is not possible to specify a cache- directive for a specific cache.
051 *
052 * <p class='bcode'>
053 *    Cache-Control   = "Cache-Control" ":" 1#cache-directive
054 *    cache-directive = cache-request-directive
055 *         | cache-response-directive
056 *    cache-request-directive =
057 *           "no-cache"                          ; Section 14.9.1
058 *         | "no-store"                          ; Section 14.9.2
059 *         | "max-age" "=" delta-seconds         ; Section 14.9.3, 14.9.4
060 *         | "max-stale" [ "=" delta-seconds ]   ; Section 14.9.3
061 *         | "min-fresh" "=" delta-seconds       ; Section 14.9.3
062 *         | "no-transform"                      ; Section 14.9.5
063 *         | "only-if-cached"                    ; Section 14.9.4
064 *         | cache-extension                     ; Section 14.9.6
065 *    cache-response-directive =
066 *           "public"                               ; Section 14.9.1
067 *         | "private" [ "=" &lt;"&gt; 1#field-name &lt;"&gt; ] ; Section 14.9.1
068 *         | "no-cache" [ "=" &lt;"&gt; 1#field-name &lt;"&gt; ]; Section 14.9.1
069 *         | "no-store"                             ; Section 14.9.2
070 *         | "no-transform"                         ; Section 14.9.5
071 *         | "must-revalidate"                      ; Section 14.9.4
072 *         | "proxy-revalidate"                     ; Section 14.9.4
073 *         | "max-age" "=" delta-seconds            ; Section 14.9.3
074 *         | "s-maxage" "=" delta-seconds           ; Section 14.9.3
075 *         | cache-extension                        ; Section 14.9.6
076 *    cache-extension = token [ "=" ( token | quoted-string ) ]
077 * </p>
078 *
079 * <p>
080 * When a directive appears without any 1#field-name parameter, the directive applies to the entire request or response.
081 * When such a directive appears with a 1#field-name parameter, it applies only to the named field or fields, and not
082 * to the rest of the request or response. This mechanism supports extensibility; implementations of future versions
083 * of the HTTP protocol might apply these directives to header fields not defined in HTTP/1.1.
084 *
085 * <p>
086 * The cache-control directives can be broken down into these general categories:
087 * <ul>
088 *    <li>Restrictions on what are cacheable; these may only be imposed by the origin server.
089 *    <li>Restrictions on what may be stored by a cache; these may be imposed by either the origin server or the user
090 *       agent.
091 *    <li>Modifications of the basic expiration mechanism; these may be imposed by either the origin server or the
092 *       user agent.
093 *    <li>Controls over cache revalidation and reload; these may only be imposed by a user agent.
094 *    <li>Control over transformation of entities.
095 *    <li>Extensions to the caching system.
096 * </ul>
097 *
098 * <h5 class='section'>See Also:</h5><ul>
099 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommonBasics">juneau-rest-common Basics</a>
100 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
101 * </ul>
102 *
103 * @serial exclude
104 */
105@Header("Cache-Control")
106public class CacheControl extends BasicStringHeader {
107
108   //-----------------------------------------------------------------------------------------------------------------
109   // Static
110   //-----------------------------------------------------------------------------------------------------------------
111
112   private static final long serialVersionUID = 1L;
113   private static final String NAME = "Cache-Control";
114
115   /**
116    * Static creator.
117    *
118    * @param value
119    *    The header value.
120    *    <br>Can be <jk>null</jk>.
121    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
122    */
123   public static CacheControl of(String value) {
124      return value == null ? null : new CacheControl(value);
125   }
126
127   /**
128    * Static creator with delayed value.
129    *
130    * <p>
131    * Header value is re-evaluated on each call to {@link #getValue()}.
132    *
133    * @param value
134    *    The supplier of the header value.
135    *    <br>Can be <jk>null</jk>.
136    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
137    */
138   public static CacheControl of(Supplier<String> value) {
139      return value == null ? null : new CacheControl(value);
140   }
141
142   //-----------------------------------------------------------------------------------------------------------------
143   // Instance
144   //-----------------------------------------------------------------------------------------------------------------
145
146   /**
147    * Constructor.
148    *
149    * @param value
150    *    The header value.
151    *    <br>Can be <jk>null</jk>.
152    */
153   public CacheControl(String value) {
154      super(NAME, value);
155   }
156
157   /**
158    * Constructor with delayed value.
159    *
160    * <p>
161    * Header value is re-evaluated on each call to {@link #getValue()}.
162    *
163    * @param value
164    *    The supplier of the header value.
165    *    <br>Can be <jk>null</jk>.
166    */
167   public CacheControl(Supplier<String> value) {
168      super(NAME, value);
169   }
170}