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.net.*;
020import java.util.function.*;
021
022import org.apache.juneau.http.annotation.*;
023
024/**
025 * Represents a parsed <l>Location</l> HTTP response header.
026 *
027 * <p>
028 * Used in redirection, or when a new resource has been created.
029 *
030 * <h5 class='figure'>Example</h5>
031 * <p class='bcode'>
032 *    Location: http://www.w3.org/pub/WWW/People.html
033 * </p>
034 *
035 * <h5 class='topic'>RFC2616 Specification</h5>
036 *
037 * The Location response-header field is used to redirect the recipient to a location other than the Request-URI for
038 * completion of the request or identification of a new resource.
039 * For 201 (Created) responses, the Location is that of the new resource which was created by the request.
040 * For 3xx responses, the location SHOULD indicate the server's preferred URI for automatic redirection to the resource.
041 * The field value consists of a single absolute URI.
042 *
043 * <p class='bcode'>
044 *    Location       = "Location" ":" absoluteURI
045 * </p>
046 *
047 * <p>
048 * An example is:
049 * <p class='bcode'>
050 *    Location: http://www.w3.org/pub/WWW/People.html
051 * </p>
052 *
053 * <p>
054 * Note: The Content-Location header field (section 14.14) differs from Location in that the Content-Location identifies
055 * the original location of the entity enclosed in the request.
056 * It is therefore possible for a response to contain header fields for both Location and Content-Location.
057 * Also see section 13.10 for cache requirements of some methods.
058 *
059 * <h5 class='section'>See Also:</h5><ul>
060 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommonBasics">juneau-rest-common Basics</a>
061 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
062 * </ul>
063 *
064 * @serial exclude
065 */
066@Header("Location")
067public class Location extends BasicUriHeader {
068
069   //-----------------------------------------------------------------------------------------------------------------
070   // Static
071   //-----------------------------------------------------------------------------------------------------------------
072
073   private static final long serialVersionUID = 1L;
074   private static final String NAME = "Location";
075
076   /**
077    * Static creator.
078    *
079    * @param value
080    *    The header value.
081    *    <br>Must be parsable by {@link URI#create(String)}.
082    *    <br>Can be <jk>null</jk>.
083    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
084    */
085   public static Location of(String value) {
086      return value == null ? null : new Location(value);
087   }
088
089   /**
090    * Static creator.
091    *
092    * @param value
093    *    The header value.
094    *    <br>Can be <jk>null</jk>.
095    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
096    */
097   public static Location of(URI value) {
098      return value == null ? null : new Location(value);
099   }
100
101   /**
102    * Static creator with delayed value.
103    *
104    * <p>
105    * Header value is re-evaluated on each call to {@link #getValue()}.
106    *
107    * @param value
108    *    The supplier of the header value.
109    *    <br>Can be <jk>null</jk>.
110    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
111    */
112   public static Location of(Supplier<URI> value) {
113      return value == null ? null : new Location(value);
114   }
115
116   //-----------------------------------------------------------------------------------------------------------------
117   // Instance
118   //-----------------------------------------------------------------------------------------------------------------
119
120   /**
121    * Constructor.
122    *
123    * @param value
124    *    The header value.
125    *    <br>Must be parsable by {@link URI#create(String)}.
126    *    <br>Can be <jk>null</jk>.
127    */
128   public Location(String value) {
129      super(NAME, value);
130   }
131
132   /**
133    * Constructor.
134    *
135    * @param value
136    *    The header value.
137    *    <br>Can be <jk>null</jk>.
138    */
139   public Location(URI value) {
140      super(NAME, value);
141   }
142
143   /**
144    * Constructor with delayed value.
145    *
146    * <p>
147    * Header value is re-evaluated on each call to {@link #getValue()}.
148    *
149    * @param value
150    *    The supplier of the header value.
151    *    <br>Can be <jk>null</jk>.
152    */
153   public Location(Supplier<URI> value) {
154      super(NAME, value);
155   }
156}