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   private static final long serialVersionUID = 1L;
069   private static final String NAME = "Location";
070
071   /**
072    * Static creator.
073    *
074    * @param value
075    *    The header value.
076    *    <br>Must be parsable by {@link URI#create(String)}.
077    *    <br>Can be <jk>null</jk>.
078    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
079    */
080   public static Location of(String value) {
081      return value == null ? null : new Location(value);
082   }
083
084   /**
085    * Static creator with delayed value.
086    *
087    * <p>
088    * Header value is re-evaluated on each call to {@link #getValue()}.
089    *
090    * @param value
091    *    The supplier of the header value.
092    *    <br>Can be <jk>null</jk>.
093    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
094    */
095   public static Location of(Supplier<URI> value) {
096      return value == null ? null : new Location(value);
097   }
098
099   /**
100    * Static creator.
101    *
102    * @param value
103    *    The header value.
104    *    <br>Can be <jk>null</jk>.
105    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
106    */
107   public static Location of(URI value) {
108      return value == null ? null : new Location(value);
109   }
110
111   /**
112    * Constructor.
113    *
114    * @param value
115    *    The header value.
116    *    <br>Must be parsable by {@link URI#create(String)}.
117    *    <br>Can be <jk>null</jk>.
118    */
119   public Location(String value) {
120      super(NAME, value);
121   }
122
123   /**
124    * Constructor with delayed value.
125    *
126    * <p>
127    * Header value is re-evaluated on each call to {@link #getValue()}.
128    *
129    * @param value
130    *    The supplier of the header value.
131    *    <br>Can be <jk>null</jk>.
132    */
133   public Location(Supplier<URI> value) {
134      super(NAME, value);
135   }
136
137   /**
138    * Constructor.
139    *
140    * @param value
141    *    The header value.
142    *    <br>Can be <jk>null</jk>.
143    */
144   public Location(URI value) {
145      super(NAME, value);
146   }
147}