001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.http.header;
018
019import java.time.*;
020import java.util.function.*;
021
022import org.apache.juneau.http.annotation.*;
023
024/**
025 * Represents a parsed <l>Last-Modified</l> HTTP response header.
026 *
027 * <p>
028 * The last modified date for the requested object (in "HTTP-date" format as defined by RFC 7231).
029 *
030 * <h5 class='figure'>Example</h5>
031 * <p class='bcode'>
032 *    Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
033 * </p>
034 *
035 * <h5 class='topic'>RFC2616 Specification</h5>
036 *
037 * The Last-Modified entity-header field indicates the date and time at which the origin server believes the variant was
038 * last modified.
039 *
040 * <p class='bcode'>
041 *    Last-Modified  = "Last-Modified" ":" HTTP-date
042 * </p>
043 *
044 * <p>
045 * An example of its use is...
046 * <p class='bcode'>
047 *    Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
048 * </p>
049 *
050 * <p>
051 * The exact meaning of this header field depends on the implementation of the origin server and the nature of the
052 * original resource.
053 * For files, it may be just the file system last-modified time.
054 * For entities with dynamically included parts, it may be the most recent of the set of last-modify times for its
055 * component parts.
056 * For database gateways, it may be the last-update time stamp of the record.
057 * For virtual objects, it may be the last time the internal state changed.
058 *
059 * <p>
060 * An origin server MUST NOT send a Last-Modified date which is later than the server's time of message origination.
061 * In such cases, where the resource's last modification would indicate some time in the future, the server MUST replace
062 * that date with the message origination date.
063 *
064 * <p>
065 * An origin server SHOULD obtain the Last-Modified value of the entity as close as possible to the time that it
066 * generates the Date value of its response.
067 * This allows a recipient to make an accurate assessment of the entity's modification time, especially if the entity
068 * changes near the time that the response is generated.
069 *
070 * <p>
071 * HTTP/1.1 servers SHOULD send Last-Modified whenever feasible.
072 *
073 * <h5 class='section'>See Also:</h5><ul>
074 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommonBasics">juneau-rest-common Basics</a>
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 *
078 * @serial exclude
079 */
080@Header("Last-Modified")
081public class LastModified extends BasicDateHeader {
082   private static final long serialVersionUID = 1L;
083   private static final String NAME = "Last-Modified";
084
085   /**
086    * Static creator.
087    *
088    * @param value
089    *    The header value.
090    *    <br>Must be an RFC-1123 formated string (e.g. <js>"Sat, 29 Oct 1994 19:43:31 GMT"</js>).
091    *    <br>Can be <jk>null</jk>.
092    * @return A new header bean, or <jk>null</jk> if the name is <jk>null</jk> or empty or the value is <jk>null</jk>.
093    */
094   public static LastModified of(String value) {
095      return value == null ? null : new LastModified(value);
096   }
097
098   /**
099    * Static creator with delayed value.
100    *
101    * <p>
102    * Header value is re-evaluated on each call to {@link #getValue()}.
103    *
104    * @param value
105    *    The supplier of the header value.
106    *    <br>Can be <jk>null</jk>.
107    * @return A new header bean, or <jk>null</jk> if the name is <jk>null</jk> or empty or the value is <jk>null</jk>.
108    */
109   public static LastModified of(Supplier<ZonedDateTime> value) {
110      return value == null ? null : new LastModified(value);
111   }
112
113   /**
114    * Static creator.
115    *
116    * @param value
117    *    The header value.
118    *    <br>Can be <jk>null</jk>.
119    * @return A new header bean, or <jk>null</jk> if the name is <jk>null</jk> or empty or the value is <jk>null</jk>.
120    */
121   public static LastModified of(ZonedDateTime value) {
122      return value == null ? null : new LastModified(value);
123   }
124
125   /**
126    * Constructor.
127    *
128    * @param value
129    *    The header value.
130    *    <br>Must be an RFC-1123 formated string (e.g. <js>"Sat, 29 Oct 1994 19:43:31 GMT"</js>).
131    *    <br>Can be <jk>null</jk>.
132    */
133   public LastModified(String value) {
134      super(NAME, value);
135   }
136
137   /**
138    * Constructor with delayed value.
139    *
140    * <p>
141    * Header value is re-evaluated on each call to {@link #getValue()}.
142    *
143    * @param value
144    *    The supplier of the header value.
145    *    <br>Can be <jk>null</jk>.
146    */
147   public LastModified(Supplier<ZonedDateTime> value) {
148      super(NAME, value);
149   }
150
151   /**
152    * Constructor.
153    *
154    * @param value
155    *    The header value.
156    *    <br>Can be <jk>null</jk>.
157    */
158   public LastModified(ZonedDateTime value) {
159      super(NAME, value);
160   }
161}