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;
018import static org.apache.juneau.commons.utils.Shorts.*;
019
020import java.net.*;
021import java.util.*;
022import java.util.function.*;
023
024/**
025 * Category of headers that consist of a single URL value.
026 *
027 * <h2 class='figure'>Example</h2>
028 * <p class='bcode'>
029 *    Location: http://www.w3.org/pub/WWW/People.html
030 * </p>
031 *
032 * <h2 class='section'>See Also:</h2><ul>
033 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommon">juneau-rest-common</a>
034 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
035 * </ul>
036 *
037 * @serial exclude
038 */
039@SuppressWarnings({
040   "java:S2160" // equals() inherited from BasicHeader compares name+value; typed URI field is accessed via getValue()
041})
042public class BasicUriHeader extends BasicHeader {
043   private static final long serialVersionUID = 1L;
044
045   /**
046    * Static creator.
047    *
048    * @param name The header name.
049    * @param value
050    *    The header value.
051    *    <br>Must be parsable by {@link URI#create(String)}.
052    *    <br>Can be <jk>null</jk>.
053    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
054    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
055    */
056   public static BasicUriHeader of(String name, String value) {
057      return value == null ? null : new BasicUriHeader(name, value);
058   }
059
060   /**
061    * Static creator with delayed value.
062    *
063    * <p>
064    * Header value is re-evaluated on each call to {@link #getValue()}.
065    *
066    * @param name The header name.
067    * @param value
068    *    The supplier of the header value.
069    *    <br>Can be <jk>null</jk>.
070    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
071    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
072    */
073   public static BasicUriHeader of(String name, Supplier<URI> value) {
074      return value == null ? null : new BasicUriHeader(name, value);
075   }
076
077   /**
078    * Static creator.
079    *
080    * @param name The header name.
081    * @param value
082    *    The header value.
083    *    <br>Can be <jk>null</jk>.
084    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
085    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
086    */
087   public static BasicUriHeader of(String name, URI value) {
088      return value == null ? null : new BasicUriHeader(name, value);
089   }
090
091   private final URI value;
092   private final transient Supplier<URI> supplier;
093
094   /**
095    * Constructor.
096    *
097    * @param name The header name.
098    * @param value
099    *    The header value.
100    *    <br>Must be parsable by {@link URI#create(String)}.
101    *    <br>Can be <jk>null</jk> to create a header with no value.
102    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
103    */
104   public BasicUriHeader(String name, String value) {
105      super(name, value);
106      this.value = ie(value) ? null : URI.create(value);
107      this.supplier = null;
108   }
109
110   /**
111    * Constructor with delayed value.
112    *
113    * <p>
114    * Header value is re-evaluated on each call to {@link #getValue()}.
115    *
116    * @param name The header name.
117    * @param value
118    *    The supplier of the header value.
119    *    <br>Can be <jk>null</jk> to create a header with no value.
120    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
121    */
122   public BasicUriHeader(String name, Supplier<URI> value) {
123      super(name, null);
124      this.value = null;
125      supplier = value;
126   }
127
128   /**
129    * Constructor.
130    *
131    * @param name The header name.
132    * @param value
133    *    The header value.
134    *    <br>Can be <jk>null</jk> to create a header with no value.
135    * @throws IllegalArgumentException If name is <jk>null</jk> or empty.
136    */
137   public BasicUriHeader(String name, URI value) {
138      super(name, s(value));
139      this.value = value;
140      this.supplier = null;
141   }
142
143   /**
144    * Returns the header value as a {@link URI} wrapped in an {@link Optional}.
145    *
146    * @return The header value as a {@link URI} wrapped in an {@link Optional}.  Never <jk>null</jk>.
147    */
148   public Optional<URI> asUri() {
149      return o(value());
150   }
151
152   @Override /* Overridden from Header */
153   public String getValue() { return s(value()); }
154
155   /**
156    * Return the value if present, otherwise return <c>other</c>.
157    *
158    * <p>
159    * This is a shortened form for calling <c>asUri().orElse(<jv>other</jv>)</c>.
160    *
161    * @param other The value to be returned if there is no value present, can be <jk>null</jk>.
162    * @return The value, if present, otherwise <c>other</c>.
163    */
164   public URI orElse(URI other) {
165      URI x = value();
166      return nn(x) ? x : other;
167   }
168
169   /**
170    * Returns the header value as a {@link URI} wrapped in an {@link Optional}.
171    *
172    * @return The header value as a {@link URI} wrapped in an {@link Optional}.  Never <jk>null</jk>.
173    */
174   public URI toUri() {
175      return value();
176   }
177
178   private URI value() {
179      if (nn(supplier))
180         return supplier.get();
181      return value;
182   }
183}