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