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.header;
014
015import java.util.function.*;
016
017import org.apache.juneau.http.annotation.*;
018
019/**
020 * Represents a parsed <l>Location</l> HTTP response header.
021 *
022 * <p>
023 * Used in redirection, or when a new resource has been created.
024 *
025 * <h5 class='figure'>Example</h5>
026 * <p class='bcode w800'>
027 *    Location: http://www.w3.org/pub/WWW/People.html
028 * </p>
029 *
030 * <h5 class='topic'>RFC2616 Specification</h5>
031 *
032 * The Location response-header field is used to redirect the recipient to a location other than the Request-URI for
033 * completion of the request or identification of a new resource.
034 * For 201 (Created) responses, the Location is that of the new resource which was created by the request.
035 * For 3xx responses, the location SHOULD indicate the server's preferred URI for automatic redirection to the resource.
036 * The field value consists of a single absolute URI.
037 *
038 * <p class='bcode w800'>
039 *    Location       = "Location" ":" absoluteURI
040 * </p>
041 *
042 * <p>
043 * An example is:
044 * <p class='bcode w800'>
045 *    Location: http://www.w3.org/pub/WWW/People.html
046 * </p>
047 *
048 * <p>
049 * Note: The Content-Location header field (section 14.14) differs from Location in that the Content-Location identifies
050 * the original location of the entity enclosed in the request.
051 * It is therefore possible for a response to contain header fields for both Location and Content-Location.
052 * Also see section 13.10 for cache requirements of some methods.
053 *
054 * <ul class='seealso'>
055 *    <li class='extlink'>{@doc ExtRFC2616}
056 * </ul>
057 */
058@Header("Location")
059public class Location extends BasicUriHeader {
060
061   private static final long serialVersionUID = 1L;
062
063   /**
064    * Convenience creator.
065    *
066    * @param value
067    *    The header value.
068    *    <br>Can be any of the following:
069    *    <ul>
070    *       <li>{@link String}
071    *       <li>Anything else - Converted to <c>String</c> then parsed.
072    *    </ul>
073    * @return A new {@link Location} object.
074    */
075   public static Location of(Object value) {
076      if (value == null)
077         return null;
078      return new Location(value);
079   }
080
081   /**
082    * Convenience creator using supplier.
083    *
084    * <p>
085    * Header value is re-evaluated on each call to {@link #getValue()}.
086    *
087    * @param value
088    *    The header value supplier.
089    *    <br>Can be any of the following:
090    *    <ul>
091    *       <li>{@link String}
092    *       <li>Anything else - Converted to <c>String</c> then parsed.
093    *    </ul>
094    * @return A new {@link Location} object.
095    */
096   public static Location of(Supplier<?> value) {
097      if (value == null)
098         return null;
099      return new Location(value);
100   }
101
102   /**
103    * Constructor
104    *
105    * @param value
106    *    The header value.
107    *    <br>Can be any of the following:
108    *    <ul>
109    *       <li>{@link String}
110    *       <li>Anything else - Converted to <c>String</c> then parsed.
111    *       <li>A {@link Supplier} of anything on this list.
112    *    </ul>
113    */
114   public Location(Object value) {
115      super("Location", value);
116   }
117
118   /**
119    * Constructor
120    *
121    * @param value
122    *    The header value.
123    */
124   public Location(String value) {
125      this((Object)value);
126   }
127}