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