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>Date</l> HTTP request/response header. 023 * 024 * <p> 025 * The date and time that the message was sent (in "HTTP-date" format as defined by RFC 7231). 026 * 027 * <h5 class='figure'>Example</h5> 028 * <p class='bcode w800'> 029 * Date: Tue, 15 Nov 1994 08:12:31 GMT 030 * </p> 031 * 032 * <h5 class='topic'>RFC2616 Specification</h5> 033 * 034 * The Date general-header field represents the date and time at which the message was originated, having the same 035 * semantics as orig-date in RFC 822. 036 * The field value is an HTTP-date, as described in section 3.3.1; it MUST be sent in RFC 1123 [8]-date format. 037 * <p class='bcode w800'> 038 * Date = "Date" ":" HTTP-date 039 * </p> 040 * 041 * <p> 042 * An example is... 043 * <p class='bcode w800'> 044 * Date: Tue, 15 Nov 1994 08:12:31 GMT 045 * </p> 046 * 047 * <p> 048 * Origin servers MUST include a Date header field in all responses, except in these cases: 049 * <ol> 050 * <li>If the response status code is 100 (Continue) or 101 (Switching Protocols), the response MAY include a Date 051 * header field, at the server's option. 052 * <li>If the response status code conveys a server error, e.g. 500 (Internal Server Error) or 503 (Service 053 * Unavailable), and it is inconvenient or impossible to generate a valid Date. 054 * <li>If the server does not have a clock that can provide a reasonable approximation of the current time, its 055 * responses MUST NOT include a Date header field. 056 * In this case, the rules in section 14.18.1 MUST be followed. 057 * </ol> 058 * 059 * <p> 060 * A received message that does not have a Date header field MUST be assigned one by the recipient if the message will 061 * be cached by that recipient or gatewayed via a protocol which requires a Date. 062 * An HTTP implementation without a clock MUST NOT cache responses without revalidating them on every use. 063 * An HTTP cache, especially a shared cache, SHOULD use a mechanism, such as NTP, to synchronize its clock with a 064 * reliable external standard. 065 * 066 * <p> 067 * Clients SHOULD only send a Date header field in messages that include an entity-body, as in the case of the PUT and 068 * POST requests, and even then it is optional. 069 * A client without a clock MUST NOT send a Date header field in a request. 070 * 071 * <p> 072 * The HTTP-date sent in a Date header SHOULD NOT represent a date and time subsequent to the generation of the message. 073 * It SHOULD represent the best available approximation of the date and time of message generation, unless the 074 * implementation has no means of generating a reasonably accurate date and time. 075 * In theory, the date ought to represent the moment just before the entity is generated. 076 * In practice, the date can be generated at any time during the message origination without affecting its semantic 077 * value. 078 * 079 * <ul class='seealso'> 080 * <li class='extlink'>{@doc ExtRFC2616} 081 * </ul> 082 */ 083@Header("Date") 084public class Date extends BasicDateHeader { 085 086 private static final long serialVersionUID = 1L; 087 088 /** 089 * Convenience creator. 090 * 091 * @param value 092 * The header value. 093 * <br>Can be any of the following: 094 * <ul> 095 * <li><c>String</c> - An RFC-1123 formated string (e.g. <js>"Sat, 29 Oct 1994 19:43:31 GMT"</js>). 096 * <li>{@link ZonedDateTime} 097 * <li>{@link Calendar} 098 * <li>Anything else - Converted to <c>String</c>. 099 * </ul> 100 * @return A new {@link Date} object, or <jk>null</jk> if the value was null. 101 */ 102 public static Date of(Object value) { 103 if (value == null) 104 return null; 105 return new Date(value); 106 } 107 108 /** 109 * Convenience creator using supplier. 110 * 111 * <p> 112 * Header value is re-evaluated on each call to {@link #getValue()}. 113 * 114 * @param value 115 * The header value supplier. 116 * <br>Can be any of the following: 117 * <ul> 118 * <li><c>String</c> - An RFC-1123 formated string (e.g. <js>"Sat, 29 Oct 1994 19:43:31 GMT"</js>). 119 * <li>{@link ZonedDateTime} 120 * <li>{@link Calendar} 121 * <li>Anything else - Converted to <c>String</c>. 122 * </ul> 123 * @return A new {@link Date} object, or <jk>null</jk> if the value was null. 124 */ 125 public static Date of(Supplier<?> value) { 126 if (value == null) 127 return null; 128 return new Date(value); 129 } 130 131 /** 132 * Constructor. 133 * 134 * @param value 135 * The header value. 136 * <br>Can be any of the following: 137 * <ul> 138 * <li><c>String</c> - An RFC-1123 formated string (e.g. <js>"Sat, 29 Oct 1994 19:43:31 GMT"</js>). 139 * <li>{@link ZonedDateTime} 140 * <li>{@link Calendar} 141 * <li>Anything else - Converted to <c>String</c>. 142 * <li>A {@link Supplier} of anything on this list. 143 * </ul> 144 */ 145 public Date(Object value) { 146 super("Date", value); 147 } 148 149 /** 150 * Constructor 151 * 152 * @param value 153 * The header value. 154 */ 155 public Date(String value) { 156 this((Object)value); 157 } 158}