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 015import org.apache.juneau.http.annotation.*; 016 017/** 018 * Represents a parsed <l>Date</l> HTTP request/response header. 019 * 020 * <p> 021 * The date and time that the message was sent (in "HTTP-date" format as defined by RFC 7231). 022 * 023 * <h5 class='figure'>Example</h5> 024 * <p class='bcode w800'> 025 * Date: Tue, 15 Nov 1994 08:12:31 GMT 026 * </p> 027 * 028 * <h5 class='topic'>RFC2616 Specification</h5> 029 * 030 * The Date general-header field represents the date and time at which the message was originated, having the same 031 * semantics as orig-date in RFC 822. 032 * The field value is an HTTP-date, as described in section 3.3.1; it MUST be sent in RFC 1123 [8]-date format. 033 * <p class='bcode w800'> 034 * Date = "Date" ":" HTTP-date 035 * </p> 036 * 037 * <p> 038 * An example is... 039 * <p class='bcode w800'> 040 * Date: Tue, 15 Nov 1994 08:12:31 GMT 041 * </p> 042 * 043 * <p> 044 * Origin servers MUST include a Date header field in all responses, except in these cases: 045 * <ol> 046 * <li>If the response status code is 100 (Continue) or 101 (Switching Protocols), the response MAY include a Date 047 * header field, at the server's option. 048 * <li>If the response status code conveys a server error, e.g. 500 (Internal Server Error) or 503 (Service 049 * Unavailable), and it is inconvenient or impossible to generate a valid Date. 050 * <li>If the server does not have a clock that can provide a reasonable approximation of the current time, its 051 * responses MUST NOT include a Date header field. 052 * In this case, the rules in section 14.18.1 MUST be followed. 053 * </ol> 054 * 055 * <p> 056 * A received message that does not have a Date header field MUST be assigned one by the recipient if the message will 057 * be cached by that recipient or gatewayed via a protocol which requires a Date. 058 * An HTTP implementation without a clock MUST NOT cache responses without revalidating them on every use. 059 * An HTTP cache, especially a shared cache, SHOULD use a mechanism, such as NTP, to synchronize its clock with a 060 * reliable external standard. 061 * 062 * <p> 063 * Clients SHOULD only send a Date header field in messages that include an entity-body, as in the case of the PUT and 064 * POST requests, and even then it is optional. 065 * A client without a clock MUST NOT send a Date header field in a request. 066 * 067 * <p> 068 * The HTTP-date sent in a Date header SHOULD NOT represent a date and time subsequent to the generation of the message. 069 * It SHOULD represent the best available approximation of the date and time of message generation, unless the 070 * implementation has no means of generating a reasonably accurate date and time. 071 * In theory, the date ought to represent the moment just before the entity is generated. 072 * In practice, the date can be generated at any time during the message origination without affecting its semantic 073 * value. 074 * 075 * <ul class='seealso'> 076 * <li class='extlink'>{@doc RFC2616} 077 * </ul> 078 */ 079@Header(name="Date") 080public final class Date extends HeaderDate { 081 082 /** 083 * Returns a parsed <c>Date</c> header. 084 * 085 * @param value The <c>Date</c> header string. 086 * @return The parsed <c>Date</c> header, or <jk>null</jk> if the string was null. 087 */ 088 public static Date forString(String value) { 089 if (value == null) 090 return null; 091 return new Date(value); 092 } 093 094 private Date(String value) { 095 super(value); 096 } 097}