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.classic.header;
018
019import static java.time.format.DateTimeFormatter.*;
020import static java.time.temporal.ChronoUnit.*;
021import static org.apache.juneau.commons.utils.Shorts.*;
022
023import java.time.*;
024import java.util.*;
025import java.util.function.*;
026
027import org.apache.juneau.bct.assertions.*;
028
029/**
030 * Category of headers that consist of a single HTTP-date.
031 *
032 * <h2 class='figure'>Example</h2>
033 * <p class='bcode'>
034 *    If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
035 * </p>
036 *
037 * <h2 class='section'>See Also:</h2><ul>
038 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommon">juneau-rest-common</a>
039 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
040 * </ul>
041 *
042 * @serial exclude
043 */
044@SuppressWarnings({
045   "java:S2160" // equals() inherited from BasicHeader compares name+value; typed ZonedDateTime field is accessed via getValue()
046})
047public class BasicDateHeader extends BasicHeader {
048   private static final long serialVersionUID = 1L;
049
050   /**
051    * Static creator.
052    *
053    * @param name The header name.
054    * @param value
055    *    The header value.
056    *    <br>Must be an RFC-1123 formated string (e.g. <js>"Sat, 29 Oct 1994 19:43:31 GMT"</js>).
057    *    <br>Can be <jk>null</jk>.
058    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
059    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
060    */
061   public static BasicDateHeader of(String name, String value) {
062      return value == null ? null : new BasicDateHeader(name, value);
063   }
064
065   /**
066    * Static creator with delayed value.
067    *
068    * <p>
069    * Header value is re-evaluated on each call to {@link #getValue()}.
070    *
071    * @param name The header name.
072    * @param value
073    *    The supplier of the header value.
074    *    <br>Can be <jk>null</jk>.
075    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
076    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
077    */
078   public static BasicDateHeader of(String name, Supplier<ZonedDateTime> value) {
079      return value == null ? null : new BasicDateHeader(name, value);
080   }
081
082   /**
083    * Static creator.
084    *
085    * @param name The header name.
086    * @param value
087    *    The header value.
088    *    <br>Can be <jk>null</jk>.
089    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
090    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
091    */
092   public static BasicDateHeader of(String name, ZonedDateTime value) {
093      return value == null ? null : new BasicDateHeader(name, value);
094   }
095
096   private final ZonedDateTime value;
097   private final transient Supplier<ZonedDateTime> supplier;
098
099   /**
100    * Constructor.
101    *
102    * @param name The header name.
103    * @param value
104    *    The header value.
105    *    <br>Must be an RFC-1123 formated string (e.g. <js>"Sat, 29 Oct 1994 19:43:31 GMT"</js>).
106    *    <br>Can be <jk>null</jk> to create a header with no value.
107    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
108    */
109   public BasicDateHeader(String name, String value) {
110      super(name, value);
111      this.value = ie(value) ? null : ZonedDateTime.from(RFC_1123_DATE_TIME.parse(value)).truncatedTo(SECONDS);
112      this.supplier = null;
113   }
114
115   /**
116    * Constructor with delayed value.
117    *
118    * <p>
119    * Header value is re-evaluated on each call to {@link #getValue()}.
120    *
121    * @param name The header name.
122    * @param value
123    *    The supplier of the header value.
124    *    <br>Can be <jk>null</jk> to create a header with no value.
125    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
126    */
127   public BasicDateHeader(String name, Supplier<ZonedDateTime> value) {
128      super(name, null);
129      this.value = null;
130      supplier = value;
131   }
132
133   /**
134    * Constructor.
135    *
136    * @param name The header name.
137    * @param value
138    *    The header value.
139    *    <br>Can be <jk>null</jk> to create a header with no value.
140    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
141    */
142   public BasicDateHeader(String name, ZonedDateTime value) {
143      super(name, value);
144      this.value = value;
145      this.supplier = null;
146   }
147
148   /**
149    * Provides the ability to perform fluent-style assertions on this header.
150    *
151    * <h4 class='section'>Examples:</h4>
152    * <p class='bjava'>
153    *    <jc>// Validates the response body content is not expired.</jc>
154    *    <jv>client</jv>
155    *       .get(<jsf>URL</jsf>)
156    *       .run()
157    *       .getHeader(<js>"Expires"</js>).asDateHeader().assertZonedDateTime().isLessThan(<jk>new</jk> Date());
158    * </p>
159    *
160    * @return A new fluent assertion object.
161    * @throws AssertionError If assertion failed.
162    */
163   public FluentZonedDateTimeAssertion<BasicDateHeader> assertZonedDateTime() {
164      return new FluentZonedDateTimeAssertion<>(value(), this);
165   }
166
167   /**
168    * Returns the header value as a {@link ZonedDateTime} wrapped in an {@link Optional}.
169    *
170    * @return The header value as a {@link ZonedDateTime} wrapped in an {@link Optional}.  Never <jk>null</jk>.
171    */
172   public Optional<ZonedDateTime> asZonedDateTime() {
173      return o(value());
174   }
175
176   @Override /* Overridden from Header */
177   public String getValue() {
178      ZonedDateTime x = value();
179      return x == null ? null : RFC_1123_DATE_TIME.format(x);
180   }
181
182   /**
183    * Return the value if present, otherwise return <c>other</c>.
184    *
185    * <p>
186    * This is a shortened form for calling <c>asZonedDateTime().orElse(<jv>other</jv>)</c>.
187    *
188    * @param other The value to be returned if there is no value present, can be <jk>null</jk>.
189    * @return The value, if present, otherwise <c>other</c>.
190    */
191   public ZonedDateTime orElse(ZonedDateTime other) {
192      ZonedDateTime x = value();
193      return nn(x) ? x : other;
194   }
195
196   /**
197    * Returns the header value as a {@link ZonedDateTime}.
198    *
199    * @return The header value as a {@link ZonedDateTime}, or <jk>null</jk> if the header has no value.
200    */
201   public ZonedDateTime toZonedDateTime() {
202      return value();
203   }
204
205   private ZonedDateTime value() {
206      if (nn(supplier))
207         return supplier.get();
208      return value;
209   }
210}