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.classic.header; 018 019import static org.apache.juneau.commons.utils.Shorts.*; 020 021import java.util.*; 022import java.util.function.*; 023 024import org.apache.juneau.commons.http.*; 025 026 027/** 028 * Category of headers that consist of simple comma-delimited lists of strings with q-values. 029 * 030 * <h2 class='figure'>Example</h2> 031 * <p class='bcode'> 032 * Accept-Encoding: compress;q=0.5, gzip;q=1.0 033 * </p> 034 * 035 * <h2 class='section'>See Also:</h2><ul> 036 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauRestCommon">juneau-rest-common</a> 037 * <li class='extlink'><a class="doclink" href="https://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext Transfer Protocol -- HTTP/1.1</a> 038 * </ul> 039 * 040 * @serial exclude 041 */ 042@SuppressWarnings({ 043 "java:S2160" // equals() inherited from BasicHeader compares name+value; typed field is accessed via getValue() 044}) 045public class BasicStringRangesHeader extends BasicHeader { 046 private static final long serialVersionUID = 1L; 047 048 /** 049 * Static creator. 050 * 051 * @param name The header name. 052 * @param value 053 * The header value. 054 * <br>Must be parsable by {@link StringRanges#of(String)}. 055 * <br>Can be <jk>null</jk>. 056 * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>. 057 * @throws IllegalArgumentException If name is <jk>null</jk> or empty. 058 */ 059 public static BasicStringRangesHeader of(String name, String value) { 060 return value == null ? null : new BasicStringRangesHeader(name, value); 061 } 062 063 /** 064 * Static creator. 065 * 066 * @param name The header name. 067 * @param value 068 * The header value. 069 * <br>Can be <jk>null</jk>. 070 * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>. 071 * @throws IllegalArgumentException If name is <jk>null</jk> or empty. 072 */ 073 public static BasicStringRangesHeader of(String name, StringRanges value) { 074 return value == null ? null : new BasicStringRangesHeader(name, value); 075 } 076 077 /** 078 * Static creator with delayed value. 079 * 080 * <p> 081 * Header value is re-evaluated on each call to {@link #getValue()}. 082 * 083 * @param name The header name. 084 * @param value 085 * The supplier of the header value. 086 * <br>Can be <jk>null</jk>. 087 * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>. 088 * @throws IllegalArgumentException If name is <jk>null</jk> or empty. 089 */ 090 public static BasicStringRangesHeader of(String name, Supplier<StringRanges> value) { 091 return value == null ? null : new BasicStringRangesHeader(name, value); 092 } 093 094 private final String stringValue; 095 private final transient StringRanges value; 096 private final transient Supplier<StringRanges> supplier; 097 098 /** 099 * Constructor. 100 * 101 * @param name The header name. 102 * @param value 103 * The header value. 104 * <br>Must be parsable by {@link StringRanges#of(String)}. 105 * <br>Can be <jk>null</jk> to create a header with no value. 106 * @throws IllegalArgumentException If name is <jk>null</jk> or empty. 107 */ 108 public BasicStringRangesHeader(String name, String value) { 109 super(name, value); 110 stringValue = value; 111 this.value = StringRanges.of(value); 112 this.supplier = null; 113 } 114 115 /** 116 * Constructor. 117 * 118 * @param name The header name. 119 * @param value 120 * The header value. 121 * <br>Can be <jk>null</jk> to create a header with no value. 122 * @throws IllegalArgumentException If name is <jk>null</jk> or empty. 123 */ 124 public BasicStringRangesHeader(String name, StringRanges value) { 125 super(name, s(value)); 126 this.stringValue = null; 127 this.value = value; 128 this.supplier = null; 129 } 130 131 /** 132 * Constructor with delayed value. 133 * 134 * <p> 135 * Header value is re-evaluated on each call to {@link #getValue()}. 136 * 137 * @param name The header name. 138 * @param value 139 * The supplier of the header value. 140 * <br>Can be <jk>null</jk> to create a header with no value. 141 * @throws IllegalArgumentException If name is <jk>null</jk> or empty. 142 */ 143 public BasicStringRangesHeader(String name, Supplier<StringRanges> value) { 144 super(name, null); 145 this.stringValue = null; 146 this.value = null; 147 supplier = value; 148 } 149 150 /** 151 * Returns the header value as a {@link StringRanges} wrapped in an {@link Optional}. 152 * 153 * @return The header value as a {@link StringRanges} wrapped in an {@link Optional}. Never <jk>null</jk>. 154 */ 155 public Optional<StringRanges> asStringRanges() { 156 return o(value()); 157 } 158 159 /** 160 * Returns the {@link MediaRange} at the specified index. 161 * 162 * @param index The index position of the media range. 163 * @return The {@link MediaRange} at the specified index or <jk>null</jk> if the index is out of range. 164 */ 165 public StringRange getRange(int index) { 166 StringRanges x = value(); 167 return x == null ? null : x.getRange(index); 168 } 169 170 @Override /* Overridden from Header */ 171 public String getValue() { return nn(stringValue) ? stringValue : s(value()); } 172 173 /** 174 * Given a list of media types, returns the best match for this string range header. 175 * 176 * <p> 177 * Note that fuzzy matching is allowed on the media types where the string range header may 178 * contain additional subtype parts. 179 * <br>For example, given identical q-values and an string range value of <js>"text/json+activity"</js>, 180 * the media type <js>"text/json"</js> will match if <js>"text/json+activity"</js> or <js>"text/activity+json"</js> 181 * isn't found. 182 * <br>The purpose for this is to allow serializers to match when artifacts such as <c>id</c> properties are 183 * present in the header. 184 * 185 * <p> 186 * See <a class="doclink" href="https://www.w3.org/TR/activitypub/#retrieving-objects">ActivityPub / Retrieving Objects</a> 187 * 188 * @param names The names to match against. 189 * @return The index into the array of the best match, or <c>-1</c> if no suitable matches could be found. 190 */ 191 public int match(List<String> names) { 192 StringRanges x = value(); 193 return x == null ? -1 : x.match(names); 194 } 195 196 /** 197 * Return the value if present, otherwise return <c>other</c>. 198 * 199 * <p> 200 * This is a shortened form for calling <c>asArray().orElse(<jv>other</jv>)</c>. 201 * 202 * @param other The value to be returned if there is no value present, can be <jk>null</jk>. 203 * @return The value, if present, otherwise <c>other</c>. 204 */ 205 public StringRanges orElse(StringRanges other) { 206 StringRanges x = value(); 207 return nn(x) ? x : other; 208 } 209 210 /** 211 * Returns the header value as a {@link StringRanges}. 212 * 213 * @return The header value as a {@link StringRanges}, or <jk>null</jk> if the header has no value. 214 */ 215 public StringRanges toStringRanges() { 216 return value(); 217 } 218 219 private StringRanges value() { 220 if (nn(supplier)) 221 return supplier.get(); 222 return value; 223 } 224}