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; 014 015import static org.apache.juneau.internal.CollectionUtils.*; 016 017import java.util.*; 018import java.util.Map.*; 019import java.util.concurrent.*; 020 021import org.apache.juneau.annotation.*; 022import org.apache.juneau.internal.*; 023 024/** 025 * Describes a single type used in content negotiation between an HTTP client and server, as described in 026 * Section 14.1 and 14.7 of RFC2616 (the HTTP/1.1 specification). 027 * 028 * <ul class='seealso'> 029 * <li class='extlink'>{@doc RFC2616} 030 * </ul> 031 */ 032@BeanIgnore 033public final class MediaTypeRange implements Comparable<MediaTypeRange> { 034 035 private static final MediaTypeRange[] DEFAULT = new MediaTypeRange[]{new MediaTypeRange("*/*")}; 036 private static final boolean NOCACHE = Boolean.getBoolean("juneau.nocache"); 037 private static final ConcurrentHashMap<String,MediaTypeRange[]> CACHE = new ConcurrentHashMap<>(); 038 039 private final MediaType mediaType; 040 private final Float qValue; 041 private final Map<String,Set<String>> extensions; 042 043 /** 044 * Parses an <c>Accept</c> header value into an array of media ranges. 045 * 046 * <p> 047 * The returned media ranges are sorted such that the most acceptable media is available at ordinal position 048 * <js>'0'</js>, and the least acceptable at position n-1. 049 * 050 * <p> 051 * The syntax expected to be found in the referenced <c>value</c> complies with the syntax described in 052 * RFC2616, Section 14.1, as described below: 053 * <p class='bcode w800'> 054 * Accept = "Accept" ":" 055 * #( media-range [ accept-params ] ) 056 * 057 * media-range = ( "*\/*" 058 * | ( type "/" "*" ) 059 * | ( type "/" subtype ) 060 * ) *( ";" parameter ) 061 * accept-params = ";" "q" "=" qvalue *( accept-extension ) 062 * accept-extension = ";" token [ "=" ( token | quoted-string ) ] 063 * </p> 064 * 065 * @param value 066 * The value to parse. 067 * If <jk>null</jk> or empty, returns a single <c>MediaTypeRange</c> is returned that represents all types. 068 * @return 069 * The media ranges described by the string. 070 * The ranges are sorted such that the most acceptable media is available at ordinal position <js>'0'</js>, and 071 * the least acceptable at position n-1. 072 */ 073 public static MediaTypeRange[] parse(String value) { 074 075 if (value == null || value.length() == 0) 076 return DEFAULT; 077 078 MediaTypeRange[] mtr = CACHE.get(value); 079 if (mtr != null) 080 return mtr; 081 082 if (value.indexOf(',') == -1) { 083 mtr = new MediaTypeRange[]{new MediaTypeRange(value)}; 084 } else { 085 Set<MediaTypeRange> ranges = new TreeSet<>(); 086 for (String r : StringUtils.split(value)) { 087 r = r.trim(); 088 if (r.isEmpty()) 089 continue; 090 ranges.add(new MediaTypeRange(r)); 091 } 092 mtr = ranges.toArray(new MediaTypeRange[ranges.size()]); 093 } 094 if (NOCACHE) 095 return mtr; 096 CACHE.putIfAbsent(value, mtr); 097 return CACHE.get(value); 098 } 099 100 private MediaTypeRange(String token) { 101 Builder b = new Builder(token); 102 this.mediaType = b.mediaType; 103 this.qValue = b.qValue; 104 this.extensions = unmodifiableMap(b.extensions); 105 } 106 107 static final class Builder { 108 MediaType mediaType; 109 Float qValue = 1f; 110 Map<String,Set<String>> extensions; 111 112 Builder(String token) { 113 114 token = token.trim(); 115 116 int i = token.indexOf(";q="); 117 118 if (i == -1) { 119 mediaType = MediaType.forString(token); 120 return; 121 } 122 123 mediaType = MediaType.forString(token.substring(0, i)); 124 125 String[] tokens = token.substring(i+1).split(";"); 126 127 // Only the type of the range is specified 128 if (tokens.length > 0) { 129 boolean isInExtensions = false; 130 for (int j = 0; j < tokens.length; j++) { 131 String[] parm = tokens[j].split("="); 132 if (parm.length == 2) { 133 String k = parm[0], v = parm[1]; 134 if (isInExtensions) { 135 if (extensions == null) 136 extensions = new TreeMap<>(); 137 if (! extensions.containsKey(k)) 138 extensions.put(k, new TreeSet<String>()); 139 extensions.get(k).add(v); 140 } else if (k.equals("q")) { 141 qValue = new Float(v); 142 isInExtensions = true; 143 } 144 } 145 } 146 } 147 } 148 } 149 150 /** 151 * Returns the media type enclosed by this media range. 152 * 153 * <h5 class='section'>Examples:</h5> 154 * <ul> 155 * <li><js>"text/html"</js> 156 * <li><js>"text/*"</js> 157 * <li><js>"*\/*"</js> 158 * </ul> 159 * 160 * @return The media type of this media range, lowercased, never <jk>null</jk>. 161 */ 162 public MediaType getMediaType() { 163 return mediaType; 164 } 165 166 /** 167 * Returns the <js>'q'</js> (quality) value for this type, as described in Section 3.9 of RFC2616. 168 * 169 * <p> 170 * The quality value is a float between <c>0.0</c> (unacceptable) and <c>1.0</c> (most acceptable). 171 * 172 * <p> 173 * If 'q' value doesn't make sense for the context (e.g. this range was extracted from a <js>"content-*"</js> 174 * header, as opposed to <js>"accept-*"</js> header, its value will always be <js>"1"</js>. 175 * 176 * @return The 'q' value for this type, never <jk>null</jk>. 177 */ 178 public Float getQValue() { 179 return qValue; 180 } 181 182 /** 183 * Returns the optional set of custom extensions defined for this type. 184 * 185 * <p> 186 * Values are lowercase and never <jk>null</jk>. 187 * 188 * @return The optional list of extensions, never <jk>null</jk>. 189 */ 190 public Map<String,Set<String>> getExtensions() { 191 return extensions; 192 } 193 194 /** 195 * Provides a string representation of this media range, suitable for use as an <c>Accept</c> header value. 196 * 197 * <p> 198 * The literal text generated will be all lowercase. 199 * 200 * @return A media range suitable for use as an Accept header value, never <c>null</c>. 201 */ 202 @Override /* Object */ 203 public String toString() { 204 StringBuffer sb = new StringBuffer().append(mediaType); 205 206 // '1' is equivalent to specifying no qValue. If there's no extensions, then we won't include a qValue. 207 if (qValue.floatValue() == 1.0) { 208 if (! extensions.isEmpty()) { 209 sb.append(";q=").append(qValue); 210 for (Entry<String,Set<String>> e : extensions.entrySet()) { 211 String k = e.getKey(); 212 for (String v : e.getValue()) 213 sb.append(';').append(k).append('=').append(v); 214 } 215 } 216 } else { 217 sb.append(";q=").append(qValue); 218 for (Entry<String,Set<String>> e : extensions.entrySet()) { 219 String k = e.getKey(); 220 for (String v : e.getValue()) 221 sb.append(';').append(k).append('=').append(v); 222 } 223 } 224 return sb.toString(); 225 } 226 227 /** 228 * Returns <jk>true</jk> if the specified object is also a <c>MediaType</c>, and has the same qValue, type, 229 * parameters, and extensions. 230 * 231 * @return <jk>true</jk> if object is equivalent. 232 */ 233 @Override /* Object */ 234 public boolean equals(Object o) { 235 236 if (o == null || !(o instanceof MediaTypeRange)) 237 return false; 238 239 if (this == o) 240 return true; 241 242 MediaTypeRange o2 = (MediaTypeRange) o; 243 return qValue.equals(o2.qValue) 244 && mediaType.equals(o2.mediaType) 245 && extensions.equals(o2.extensions); 246 } 247 248 /** 249 * Returns a hash based on this instance's <c>media-type</c>. 250 * 251 * @return A hash based on this instance's <c>media-type</c>. 252 */ 253 @Override /* Object */ 254 public int hashCode() { 255 return mediaType.hashCode(); 256 } 257 258 /** 259 * Compares two MediaRanges for equality. 260 * 261 * <p> 262 * The values are first compared according to <c>qValue</c> values. 263 * Should those values be equal, the <c>type</c> is then lexicographically compared (case-insensitive) in 264 * ascending order, with the <js>"*"</js> type demoted last in that order. 265 * <c>MediaRanges</c> with the same type but different sub-types are compared - a more specific subtype is 266 * promoted over the 'wildcard' subtype. 267 * <c>MediaRanges</c> with the same types but with extensions are promoted over those same types with no 268 * extensions. 269 * 270 * @param o The range to compare to. Never <jk>null</jk>. 271 */ 272 @Override /* Comparable */ 273 public int compareTo(MediaTypeRange o) { 274 275 // Compare q-values. 276 int qCompare = Float.compare(o.qValue, qValue); 277 if (qCompare != 0) 278 return qCompare; 279 280 // Compare media-types. 281 // Note that '*' comes alphabetically before letters, so just do a reverse-alphabetical comparison. 282 int i = o.mediaType.toString().compareTo(mediaType.toString()); 283 return i; 284 } 285}