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;
014
015/**
016 * Represents a parsed <l>Expires</l> HTTP response header.
017 * 
018 * <p>
019 * Gives the date/time after which the response is considered stale (in "HTTP-date" format as defined by RFC 7231).
020 * 
021 * <h5 class='figure'>Example</h5>
022 * <p class='bcode'>
023 *    Expires: Thu, 01 Dec 1994 16:00:00 GMT
024 * </p>
025 * 
026 * <h5 class='topic'>RFC2616 Specification</h5>
027 * 
028 * The Expires entity-header field gives the date/time after which the response is considered stale.
029 * A stale cache entry may not normally be returned by a cache (either a proxy cache or a user agent cache) unless it is
030 * first validated with the origin server
031 * (or with an intermediate cache that has a fresh copy of the entity).
032 * See section 13.2 for further discussion of the expiration model.
033 * 
034 * <p>
035 * The presence of an Expires field does not imply that the original resource will change or cease to exist at, before,
036 * or after that time.
037 * 
038 * <p>
039 * 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:
040 * 
041 * <p class='bcode'>
042 *    Expires = "Expires" ":" HTTP-date
043 * </p>
044 * 
045 * <p>
046 * An example of its use is...
047 * <p class='bcode'>
048 *    Expires: Thu, 01 Dec 1994 16:00:00 GMT
049 * </p>
050 * 
051 * <p>
052 * Note: if a response includes a Cache-Control field with the max-age directive (see section 14.9.3), that directive
053 * overrides the Expires field.
054 * 
055 * <p>
056 * HTTP/1.1 clients and caches MUST treat other invalid date formats, especially including the value "0", as in the past
057 * (i.e., "already expired").
058 * 
059 * <p>
060 * To mark a response as "already expired," an origin server sends an Expires date that is equal to the Date header
061 * value.
062 * (See the rules for expiration calculations in section 13.2.4.)
063 * 
064 * <p>
065 * To mark a response as "never expires," an origin server sends an Expires date approximately one year from the time
066 * the response is sent.
067 * HTTP/1.1 servers SHOULD NOT send Expires dates more than one year in the future.
068 * 
069 * <p>
070 * The presence of an Expires header field with a date value of some time in the future on a response that otherwise
071 * would by default be non-cacheable indicates that the response is cacheable, unless indicated otherwise by a
072 * Cache-Control header field (section 14.9).
073 * 
074 * <h5 class='section'>See Also:</h5>
075 * <ul class='doctree'>
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 */
079public final class Expires extends HeaderDate {
080
081   /**
082    * Returns a parsed <code>Expires</code> header.
083    * 
084    * @param value The <code>Expires</code> header string.
085    * @return The parsed <code>Expires</code> header, or <jk>null</jk> if the string was null.
086    */
087   public static Expires forString(String value) {
088      if (value == null)
089         return null;
090      return new Expires(value);
091   }
092
093   private Expires(String value) {
094      super(value);
095   }
096}