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