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 multiple parameterized string values. 029 * 030 * <h2 class='figure'>Example</h2> 031 * <p class='bcode'> 032 * Accept: application/json;q=0.9,text/xml;q=0.1 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 "java:S9149" // Public Juneau DSL factory; hiding parent of()/create() is intentional. 045}) 046public class BasicMediaRangesHeader extends BasicStringHeader { 047 private static final long serialVersionUID = 1L; 048 049 /** 050 * Static creator. 051 * 052 * @param name The header name. 053 * @param value 054 * The header value. 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 BasicMediaRangesHeader of(String name, MediaRanges value) { 060 return value == null ? null : new BasicMediaRangesHeader(name, value); 061 } 062 063 /** 064 * Static creator. 065 * 066 * @param name The header name. 067 * @param value 068 * The header value. 069 * <br>Must be parsable by {@link MediaRanges#of(String)}. 070 * <br>Can be <jk>null</jk>. 071 * @return A new header bean, or <jk>null</jk> if the value is <jk>null</jk>. 072 * @throws IllegalArgumentException If name is <jk>null</jk> or empty. 073 */ 074 public static BasicMediaRangesHeader of(String name, String value) { 075 return value == null ? null : new BasicMediaRangesHeader(name, value); 076 } 077 078 private final String stringValue; 079 private final transient MediaRanges value; 080 private final transient Supplier<MediaRanges> supplier; 081 082 /** 083 * Constructor. 084 * 085 * @param name The header name. 086 * @param value 087 * The header value. 088 * <br>Can be <jk>null</jk> to create a header with no value. 089 * @throws IllegalArgumentException If name is <jk>null</jk> or empty. 090 */ 091 public BasicMediaRangesHeader(String name, MediaRanges value) { 092 super(name, s(value)); 093 this.stringValue = null; 094 this.value = value; 095 this.supplier = null; 096 } 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 MediaRanges#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 BasicMediaRangesHeader(String name, String value) { 109 super(name, value); 110 stringValue = value; 111 this.value = parse(value); 112 this.supplier = null; 113 } 114 115 /** 116 * Constructor with delayed value. 117 * 118 * <p> 119 * Header value is re-evaluated on each call to {@link #getValue()}. 120 * 121 * @param name The header name. 122 * @param value 123 * The supplier of the header value. 124 * <br>Can be <jk>null</jk> to create a header with no value. 125 * @throws IllegalArgumentException If name is <jk>null</jk> or empty. 126 */ 127 public BasicMediaRangesHeader(String name, Supplier<MediaRanges> value) { 128 super(name, (String)null); 129 this.stringValue = null; 130 this.value = null; 131 supplier = value; 132 } 133 134 /** 135 * Returns the header value as a {@link MediaRanges} wrapped in an {@link Optional}. 136 * 137 * @return The header value as a {@link MediaRanges} wrapped in an {@link Optional}. Never <jk>null</jk>. 138 */ 139 public Optional<MediaRanges> asMediaRanges() { 140 return o(value()); 141 } 142 143 /** 144 * Returns the {@link MediaRange} at the specified index. 145 * 146 * @param index The index position of the media range. 147 * @return The {@link MediaRange} at the specified index or <jk>null</jk> if the index is out of range. 148 */ 149 public MediaRange getRange(int index) { 150 MediaRanges x = value(); 151 return x == null ? null : x.getRange(index); 152 } 153 154 @Override /* Overridden from Header */ 155 public String getValue() { return nn(stringValue) ? stringValue : s(value()); } 156 157 /** 158 * Convenience method for searching through all of the subtypes of all the media ranges in this header for the 159 * presence of a subtype fragment. 160 * 161 * <p> 162 * For example, given the header <js>"text/json+activity"</js>, calling 163 * <code>hasSubtypePart(<js>"activity"</js>)</code> returns <jk>true</jk>. 164 * 165 * @param part The media type subtype fragment. 166 * @return <jk>true</jk> if subtype fragment exists. 167 */ 168 public boolean hasSubtypePart(String part) { 169 MediaRanges x = value(); 170 return x != null && x.hasSubtypePart(part); 171 } 172 173 /** 174 * Given a list of media types, returns the best match for this <c>Accept</c> header. 175 * 176 * <p> 177 * Note that fuzzy matching is allowed on the media types where the <c>Accept</c> header may 178 * contain additional subtype parts. 179 * <br>For example, given identical q-values and an <c>Accept</c> 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 mediaTypes The media types 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<? extends MediaType> mediaTypes) { 192 MediaRanges x = value(); 193 return x == null ? -1 : x.match(mediaTypes); 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>asMediaRanges().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 MediaRanges orElse(MediaRanges other) { 206 MediaRanges x = value(); 207 return nn(x) ? x : other; 208 } 209 210 /** 211 * Returns the header value as a {@link MediaRanges}. 212 * 213 * @return The header value as a {@link MediaRanges}, or <jk>null</jk> if the header has no value. 214 */ 215 public MediaRanges toMediaRanges() { 216 return value(); 217 } 218 219 private static MediaRanges parse(String value) { 220 return value == null ? null : MediaRanges.of(value); 221 } 222 223 @SuppressWarnings({ 224 "java:S2177" // Intentional: subclass provides its own private value() with a different return type (MediaRanges vs String) 225 }) 226 private MediaRanges value() { 227 if (nn(supplier)) 228 return supplier.get(); 229 return value; 230 } 231}