/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.juneau.rest.client;

import static org.apache.juneau.commons.utils.Shorts.*;

import java.net.*;
import java.time.*;
import java.util.*;

import org.apache.juneau.commons.http.*;
import org.apache.juneau.http.header.*;

/**
 * A fluent accessor for a named HTTP response header.
 *
 * <p>
 * Provides convenient typed-access methods for reading header values.
 * Returns {@code null} or empty results when the named header is absent from the response.
 *
 * <p>
 * Obtain instances via {@link RestResponse#header(String)}.
 *
 * <h5 class='section'>See Also:</h5><ul>
 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/NextGenRestClient">Next-Generation REST Client</a>
 * </ul>
 *
 * @since 9.2.1
 */
@SuppressWarnings({
   "resource" // Eclipse resource analysis: response is borrowed; caller closes it
})
public final class ResponseHeader {

   private final String name;

   private final RestResponse response;

   ResponseHeader(String name, RestResponse response) {
      this.name = name;
      this.response = response;
   }

   /**
    * Returns the header name.
    *
    * @return The header name. Never <jk>null</jk>.
    */
   public String getName() {
      return name;
   }

   /**
    * Returns <jk>true</jk> if this header is present in the response.
    *
    * @return <jk>true</jk> if present.
    */
   public boolean isPresent() {
      return response.getFirstHeader(name) != null;
   }

   /**
    * Returns the first value of this header, or <jk>null</jk> if absent.
    *
    * @return The header value, possibly <jk>null</jk>.
    */
   public String getValue() {
      var h = response.getFirstHeader(name);
      return h != null ? h.value() : null;
   }

   /**
    * Returns the first value of this header, or the given default if absent.
    *
    * @param defaultValue The default value to return when the header is absent.
    * @return The header value, or {@code defaultValue} if absent.
    */
   public String orElse(String defaultValue) {
      var value = getValue();
      return or(value, defaultValue);
   }

   /**
    * Returns the first value of this header as an {@link Optional}.
    *
    * @return An optional containing the first header value, or empty if absent.
    */
   public Optional<String> asOptional() {
      return o(getValue());
   }

   /**
    * Returns the first value of this header parsed as an {@code int}, or {@code -1} if absent or not parseable.
    *
    * @return The integer value, or {@code -1} if absent or not an integer.
    */
   public int asInteger() {
      var value = getValue();
      if (value == null)
         return -1;
      try {
         return Integer.parseInt(value.trim());
      } catch (NumberFormatException e) {
         return -1;
      }
   }

   /**
    * Returns the first value of this header parsed as a {@code long}, or {@code -1L} if absent or not parseable.
    *
    * @return The long value, or {@code -1L} if absent or not a long.
    */
   public long asLong() {
      var value = getValue();
      if (value == null)
         return -1L;
      try {
         return Long.parseLong(value.trim());
      } catch (NumberFormatException e) {
         return -1L;
      }
   }

   /**
    * Returns all values of this header.
    *
    * <p>
    * For repeated headers, this returns each header value in encounter order.
    *
    * @return An unmodifiable list of header values. Never <jk>null</jk>, but possibly empty.
    */
   public List<String> getValues() {
      return response.getHeaders().stream()
         .filter(h -> eqic(name, h.name()))
         .map(TransportHeader::value)
         .toList();
   }

   /**
    * Returns the first value as a comma-split list of individual tokens.
    *
    * <p>
    * Useful for headers like {@code Accept} or {@code Allow} that combine multiple values with commas.
    *
    * @return A list of trimmed tokens. Never <jk>null</jk>, but possibly empty.
    */
   public List<String> asCsvList() {
      var value = getValue();
      if (value == null)
         return List.of();
      return Arrays.stream(value.split(","))
         .map(String::trim)
         .filter(s -> !s.isEmpty())
         .toList();
   }

   /**
    * Returns the first value of this header parsed as a {@link Boolean}.
    *
    * @return The boolean value, or empty if absent.
    */
   public Optional<Boolean> asBoolean() {
      var value = getValue();
      return value == null ? oe() : o(Boolean.parseBoolean(value.trim()));
   }

   /**
    * Returns the first value of this header parsed as an RFC-1123 HTTP date.
    *
    * @return The parsed date, or empty if absent or not parseable.
    */
   public Optional<ZonedDateTime> asZonedDateTime() {
      var value = getValue();
      if (value == null)
         return oe();
      try {
         return HttpDateHeader.of(name, value).asZonedDateTime();
      } catch (DateTimeException e) {
         return oe();
      }
   }

   /**
    * Returns the first value of this header parsed as a {@link URI}.
    *
    * @return The parsed URI, or empty if absent or not a valid URI.
    */
   public Optional<URI> asUri() {
      var value = getValue();
      if (value == null)
         return oe();
      try {
         return o(new URI(value));
      } catch (URISyntaxException e) {
         return oe();
      }
   }

   /**
    * Returns the first value of this header parsed as a single {@link EntityTag} validator (e.g. {@code ETag}).
    *
    * @return The parsed entity tag, or empty if absent.
    */
   public Optional<EntityTag> asEntityTag() {
      try {
         return o(EntityTag.of(getValue()));
      } catch (IllegalArgumentException e) {
         return oe();
      }
   }

   /**
    * Returns the first value of this header parsed as a comma-delimited list of {@link EntityTag} validators
    * (e.g. {@code If-Match}).
    *
    * @return The parsed entity tags, or {@link EntityTags#EMPTY} if absent or not parseable. Never <jk>null</jk>.
    */
   public EntityTags asEntityTags() {
      try {
         return EntityTags.of(getValue());
      } catch (IllegalArgumentException e) {
         return EntityTags.EMPTY;
      }
   }

   /**
    * Returns the first value of this header parsed as a q-valued list of string ranges (e.g. {@code Accept-Encoding}).
    *
    * @return The parsed string ranges. Never <jk>null</jk>, but possibly empty.
    */
   public StringRanges asStringRanges() {
      return StringRanges.of(getValue());
   }

   @Override /* Object */
   public String toString() {
      var value = getValue();
      return value != null ? name + ": " + value : name + ": <absent>";
   }
}