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.time.*;
016import java.util.function.*;
017
018import org.apache.juneau.http.annotation.*;
019
020/**
021 * Represents a parsed <l>Expires</l> HTTP response header.
022 *
023 * <p>
024 * Gives the date/time after which the response is considered stale (in "HTTP-date" format as defined by RFC 7231).
025 *
026 * <h5 class='figure'>Example</h5>
027 * <p class='bcode'>
028 *    Expires: Thu, 01 Dec 1994 16:00:00 GMT
029 * </p>
030 *
031 * <h5 class='topic'>RFC2616 Specification</h5>
032 *
033 * The Expires entity-header field gives the date/time after which the response is considered stale.
034 * A stale cache entry may not normally be returned by a cache (either a proxy cache or a user agent cache) unless it is
035 * first validated with the origin server
036 * (or with an intermediate cache that has a fresh copy of the entity).
037 * See section 13.2 for further discussion of the expiration model.
038 *
039 * <p>
040 * The presence of an Expires field does not imply that the original resource will change or cease to exist at, before,
041 * or after that time.
042 *
043 * <p>
044 * The format is an absolute date and time as defined by HTTP-date in section 3.3.1; it MUST be in RFC 1123 date format:
045 *
046 * <p class='bcode'>
047 *    Expires = "Expires" ":" HTTP-date
048 * </p>
049 *
050 * <p>
051 * An example of its use is...
052 * <p class='bcode'>
053 *    Expires: Thu, 01 Dec 1994 16:00:00 GMT
054 * </p>
055 *
056 * <p>
057 * Note: if a response includes a Cache-Control field with the max-age directive (see section 14.9.3), that directive
058 * overrides the Expires field.
059 *
060 * <p>
061 * HTTP/1.1 clients and caches MUST treat other invalid date formats, especially including the value "0", as in the past
062 * (i.e., "already expired").
063 *
064 * <p>
065 * To mark a response as "already expired," an origin server sends an Expires date that is equal to the Date header
066 * value.
067 * (See the rules for expiration calculations in section 13.2.4.)
068 *
069 * <p>
070 * To mark a response as "never expires," an origin server sends an Expires date approximately one year from the time
071 * the response is sent.
072 * HTTP/1.1 servers SHOULD NOT send Expires dates more than one year in the future.
073 *
074 * <p>
075 * The presence of an Expires header field with a date value of some time in the future on a response that otherwise
076 * would by default be non-cacheable indicates that the response is cacheable, unless indicated otherwise by a
077 * Cache-Control header field (section 14.9).
078 *
079 * <h5 class='section'>See Also:</h5><ul>
080 *    <li class='link'><a class="doclink" href="../../../../../index.html#juneau-rest-common">juneau-rest-common</a>
081 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
082 * </ul>
083 *
084 * @serial exclude
085 */
086@Header("Expires")
087public class Expires extends BasicDateHeader {
088
089   //-----------------------------------------------------------------------------------------------------------------
090   // Static
091   //-----------------------------------------------------------------------------------------------------------------
092
093   private static final long serialVersionUID = 1L;
094   private static final String NAME = "Expires";
095
096   /**
097    * Static creator.
098    *
099    * @param value
100    *    The header value.
101    *    <br>Must be an RFC-1123 formated string (e.g. <js>"Sat, 29 Oct 1994 19:43:31 GMT"</js>).
102    *    <br>Can be <jk>null</jk>.
103    * @return A new header bean, or <jk>null</jk> if the name is <jk>null</jk> or empty or the value is <jk>null</jk>.
104    */
105   public static Expires of(String value) {
106      return value == null ? null : new Expires(value);
107   }
108
109   /**
110    * Static creator.
111    *
112    * @param value
113    *    The header value.
114    *    <br>Can be <jk>null</jk>.
115    * @return A new header bean, or <jk>null</jk> if the name is <jk>null</jk> or empty or the value is <jk>null</jk>.
116    */
117   public static Expires of(ZonedDateTime value) {
118      return value == null ? null : new Expires(value);
119   }
120
121   /**
122    * Static creator with delayed value.
123    *
124    * <p>
125    * Header value is re-evaluated on each call to {@link #getValue()}.
126    *
127    * @param value
128    *    The supplier of the header value.
129    *    <br>Can be <jk>null</jk>.
130    * @return A new header bean, or <jk>null</jk> if the name is <jk>null</jk> or empty or the value is <jk>null</jk>.
131    */
132   public static Expires of(Supplier<ZonedDateTime> value) {
133      return value == null ? null : new Expires(value);
134   }
135
136   //-----------------------------------------------------------------------------------------------------------------
137   // Instance
138   //-----------------------------------------------------------------------------------------------------------------
139
140   /**
141    * Constructor.
142    *
143    * @param value
144    *    The header value.
145    *    <br>Must be an RFC-1123 formated string (e.g. <js>"Sat, 29 Oct 1994 19:43:31 GMT"</js>).
146    *    <br>Can be <jk>null</jk>.
147    */
148   public Expires(String value) {
149      super(NAME, value);
150   }
151
152   /**
153    * Constructor.
154    *
155    * @param value
156    *    The header value.
157    *    <br>Can be <jk>null</jk>.
158    */
159   public Expires(ZonedDateTime value) {
160      super(NAME, value);
161   }
162
163   /**
164    * Constructor with delayed value.
165    *
166    * <p>
167    * Header value is re-evaluated on each call to {@link #getValue()}.
168    *
169    * @param value
170    *    The supplier of the header value.
171    *    <br>Can be <jk>null</jk>.
172    */
173   public Expires(Supplier<ZonedDateTime> value) {
174      super(NAME, value);
175   }
176}