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}