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.net.*;
016import java.util.function.*;
017
018import org.apache.juneau.http.annotation.*;
019
020/**
021 * Represents a parsed <l>Content-Location</l> HTTP response header.
022 *
023 * <p>
024 * An alternate location for the returned data.
025 *
026 * <h5 class='figure'>Example</h5>
027 * <p class='bcode'>
028 *    Content-Location: /index.htm
029 * </p>
030 *
031 * <h5 class='topic'>RFC2616 Specification</h5>
032 *
033 * The Content-Location entity-header field MAY be used to supply the resource location for the entity enclosed in the
034 * message when that entity is accessible from a location separate from the requested resource's URI.
035 * A server SHOULD provide a Content-Location for the variant corresponding to the response entity; especially in the
036 * case where a resource has multiple entities associated with it, and those entities actually have separate locations
037 * by which they might be individually accessed, the server SHOULD provide a Content-Location for the particular variant
038 * which is returned.
039 * <p class='bcode'>
040 *    Content-Location = "Content-Location" ":"
041 *                       ( absoluteURI | relativeURI )
042 * </p>
043 *
044 * <p>
045 * The value of Content-Location also defines the base URI for the entity.
046 *
047 * <p>
048 * The Content-Location value is not a replacement for the original requested URI; it is only a statement of the
049 * location of the resource corresponding to this particular entity at the time of the request.
050 * Future requests MAY specify the Content-Location URI as the request- URI if the desire is to identify the source of
051 * that particular entity.
052 *
053 * <p>
054 * A cache cannot assume that an entity with a Content-Location different from the URI used to retrieve it can be used
055 * to respond to later requests on that Content-Location URI.
056 * However, the Content- Location can be used to differentiate between multiple entities retrieved from a single
057 * requested resource, as described in section 13.6.
058 *
059 * <p>
060 * If the Content-Location is a relative URI, the relative URI is interpreted relative to the Request-URI.
061 *
062 * <p>
063 * The meaning of the Content-Location header in PUT or POST requests is undefined; servers are free to ignore it in
064 * those cases.
065 *
066 * <h5 class='section'>See Also:</h5><ul>
067 *    <li class='link'><a class="doclink" href="../../../../../index.html#juneau-rest-common">juneau-rest-common</a>
068 *    <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a>
069 * </ul>
070 *
071 * @serial exclude
072 */
073@Header("Content-Location")
074public class ContentLocation extends BasicUriHeader {
075
076   //-----------------------------------------------------------------------------------------------------------------
077   // Static
078   //-----------------------------------------------------------------------------------------------------------------
079
080   private static final long serialVersionUID = 1L;
081   private static final String NAME = "Content-Location";
082
083   /**
084    * Static creator.
085    *
086    * @param value
087    *    The header value.
088    *    <br>Must be parsable by {@link URI#create(String)}.
089    *    <br>Can be <jk>null</jk>.
090    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
091    */
092   public static ContentLocation of(String value) {
093      return value == null ? null : new ContentLocation(value);
094   }
095
096   /**
097    * Static creator.
098    *
099    * @param value
100    *    The header value.
101    *    <br>Can be <jk>null</jk>.
102    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
103    */
104   public static ContentLocation of(URI value) {
105      return value == null ? null : new ContentLocation(value);
106   }
107
108   /**
109    * Static creator with delayed value.
110    *
111    * <p>
112    * Header value is re-evaluated on each call to {@link #getValue()}.
113    *
114    * @param value
115    *    The supplier of the header value.
116    *    <br>Can be <jk>null</jk>.
117    * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>.
118    */
119   public static ContentLocation of(Supplier<URI> value) {
120      return value == null ? null : new ContentLocation(value);
121   }
122
123   //-----------------------------------------------------------------------------------------------------------------
124   // Instance
125   //-----------------------------------------------------------------------------------------------------------------
126
127   /**
128    * Constructor.
129    *
130    * @param value
131    *    The header value.
132    *    <br>Must be parsable by {@link URI#create(String)}.
133    *    <br>Can be <jk>null</jk>.
134    */
135   public ContentLocation(String value) {
136      super(NAME, value);
137   }
138
139   /**
140    * Constructor.
141    *
142    * @param value
143    *    The header value.
144    *    <br>Can be <jk>null</jk>.
145    */
146   public ContentLocation(URI value) {
147      super(NAME, value);
148   }
149
150   /**
151    * Constructor with delayed value.
152    *
153    * <p>
154    * Header value is re-evaluated on each call to {@link #getValue()}.
155    *
156    * @param value
157    *    The supplier of the header value.
158    *    <br>Can be <jk>null</jk>.
159    */
160   public ContentLocation(Supplier<URI> value) {
161      super(NAME, value);
162   }
163}