001/*
002 * Copyright (C) 2011 The Guava Authors
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005 * in compliance 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
010 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011 * or implied. See the License for the specific language governing permissions and limitations under
012 * the License.
013 */
014
015package com.google.common.net;
016
017import static com.google.common.base.CharMatcher.ascii;
018import static com.google.common.base.CharMatcher.javaIsoControl;
019import static com.google.common.base.Charsets.UTF_8;
020import static com.google.common.base.Preconditions.checkArgument;
021import static com.google.common.base.Preconditions.checkNotNull;
022import static com.google.common.base.Preconditions.checkState;
023
024import com.google.common.annotations.Beta;
025import com.google.common.annotations.GwtCompatible;
026import com.google.common.base.Ascii;
027import com.google.common.base.CharMatcher;
028import com.google.common.base.Function;
029import com.google.common.base.Joiner;
030import com.google.common.base.Joiner.MapJoiner;
031import com.google.common.base.MoreObjects;
032import com.google.common.base.Objects;
033import com.google.common.base.Optional;
034import com.google.common.collect.ImmutableListMultimap;
035import com.google.common.collect.ImmutableMultiset;
036import com.google.common.collect.ImmutableSet;
037import com.google.common.collect.Maps;
038import com.google.common.collect.Multimap;
039import com.google.common.collect.Multimaps;
040import com.google.errorprone.annotations.Immutable;
041import com.google.errorprone.annotations.concurrent.LazyInit;
042import java.nio.charset.Charset;
043import java.nio.charset.IllegalCharsetNameException;
044import java.nio.charset.UnsupportedCharsetException;
045import java.util.Collection;
046import java.util.Map;
047import java.util.Map.Entry;
048import org.checkerframework.checker.nullness.qual.Nullable;
049
050/**
051 * Represents an <a href="http://en.wikipedia.org/wiki/Internet_media_type">Internet Media Type</a>
052 * (also known as a MIME Type or Content Type). This class also supports the concept of media ranges
053 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1">defined by HTTP/1.1</a>.
054 * As such, the {@code *} character is treated as a wildcard and is used to represent any acceptable
055 * type or subtype value. A media type may not have wildcard type with a declared subtype. The
056 * {@code *} character has no special meaning as part of a parameter. All values for type, subtype,
057 * parameter attributes or parameter values must be valid according to RFCs <a
058 * href="http://www.ietf.org/rfc/rfc2045.txt">2045</a> and <a
059 * href="http://www.ietf.org/rfc/rfc2046.txt">2046</a>.
060 *
061 * <p>All portions of the media type that are case-insensitive (type, subtype, parameter attributes)
062 * are normalized to lowercase. The value of the {@code charset} parameter is normalized to
063 * lowercase, but all others are left as-is.
064 *
065 * <p>Note that this specifically does <strong>not</strong> represent the value of the MIME {@code
066 * Content-Type} header and as such has no support for header-specific considerations such as line
067 * folding and comments.
068 *
069 * <p>For media types that take a charset the predefined constants default to UTF-8 and have a
070 * "_UTF_8" suffix. To get a version without a character set, use {@link #withoutParameters}.
071 *
072 * @since 12.0
073 * @author Gregory Kick
074 */
075@Beta
076@GwtCompatible
077@Immutable
078public final class MediaType {
079  private static final String CHARSET_ATTRIBUTE = "charset";
080  private static final ImmutableListMultimap<String, String> UTF_8_CONSTANT_PARAMETERS =
081      ImmutableListMultimap.of(CHARSET_ATTRIBUTE, Ascii.toLowerCase(UTF_8.name()));
082
083  /** Matcher for type, subtype and attributes. */
084  private static final CharMatcher TOKEN_MATCHER =
085      ascii()
086          .and(javaIsoControl().negate())
087          .and(CharMatcher.isNot(' '))
088          .and(CharMatcher.noneOf("()<>@,;:\\\"/[]?="));
089
090  private static final CharMatcher QUOTED_TEXT_MATCHER = ascii().and(CharMatcher.noneOf("\"\\\r"));
091
092  /*
093   * This matches the same characters as linear-white-space from RFC 822, but we make no effort to
094   * enforce any particular rules with regards to line folding as stated in the class docs.
095   */
096  private static final CharMatcher LINEAR_WHITE_SPACE = CharMatcher.anyOf(" \t\r\n");
097
098  // TODO(gak): make these public?
099  private static final String APPLICATION_TYPE = "application";
100  private static final String AUDIO_TYPE = "audio";
101  private static final String IMAGE_TYPE = "image";
102  private static final String TEXT_TYPE = "text";
103  private static final String VIDEO_TYPE = "video";
104
105  private static final String WILDCARD = "*";
106
107  private static final Map<MediaType, MediaType> KNOWN_TYPES = Maps.newHashMap();
108
109  private static MediaType createConstant(String type, String subtype) {
110    MediaType mediaType =
111        addKnownType(new MediaType(type, subtype, ImmutableListMultimap.<String, String>of()));
112    mediaType.parsedCharset = Optional.absent();
113    return mediaType;
114  }
115
116  private static MediaType createConstantUtf8(String type, String subtype) {
117    MediaType mediaType = addKnownType(new MediaType(type, subtype, UTF_8_CONSTANT_PARAMETERS));
118    mediaType.parsedCharset = Optional.of(UTF_8);
119    return mediaType;
120  }
121
122  private static MediaType addKnownType(MediaType mediaType) {
123    KNOWN_TYPES.put(mediaType, mediaType);
124    return mediaType;
125  }
126
127  /*
128   * The following constants are grouped by their type and ordered alphabetically by the constant
129   * name within that type. The constant name should be a sensible identifier that is closest to the
130   * "common name" of the media. This is often, but not necessarily the same as the subtype.
131   *
132   * Be sure to declare all constants with the type and subtype in all lowercase. For types that
133   * take a charset (e.g. all text/* types), default to UTF-8 and suffix the constant name with
134   * "_UTF_8".
135   */
136
137  public static final MediaType ANY_TYPE = createConstant(WILDCARD, WILDCARD);
138  public static final MediaType ANY_TEXT_TYPE = createConstant(TEXT_TYPE, WILDCARD);
139  public static final MediaType ANY_IMAGE_TYPE = createConstant(IMAGE_TYPE, WILDCARD);
140  public static final MediaType ANY_AUDIO_TYPE = createConstant(AUDIO_TYPE, WILDCARD);
141  public static final MediaType ANY_VIDEO_TYPE = createConstant(VIDEO_TYPE, WILDCARD);
142  public static final MediaType ANY_APPLICATION_TYPE = createConstant(APPLICATION_TYPE, WILDCARD);
143
144  /* text types */
145  public static final MediaType CACHE_MANIFEST_UTF_8 =
146      createConstantUtf8(TEXT_TYPE, "cache-manifest");
147  public static final MediaType CSS_UTF_8 = createConstantUtf8(TEXT_TYPE, "css");
148  public static final MediaType CSV_UTF_8 = createConstantUtf8(TEXT_TYPE, "csv");
149  public static final MediaType HTML_UTF_8 = createConstantUtf8(TEXT_TYPE, "html");
150  public static final MediaType I_CALENDAR_UTF_8 = createConstantUtf8(TEXT_TYPE, "calendar");
151  public static final MediaType PLAIN_TEXT_UTF_8 = createConstantUtf8(TEXT_TYPE, "plain");
152
153  /**
154   * <a href="http://www.rfc-editor.org/rfc/rfc4329.txt">RFC 4329</a> declares {@link
155   * #JAVASCRIPT_UTF_8 application/javascript} to be the correct media type for JavaScript, but this
156   * may be necessary in certain situations for compatibility.
157   */
158  public static final MediaType TEXT_JAVASCRIPT_UTF_8 = createConstantUtf8(TEXT_TYPE, "javascript");
159  /**
160   * <a href="http://www.iana.org/assignments/media-types/text/tab-separated-values">Tab separated
161   * values</a>.
162   *
163   * @since 15.0
164   */
165  public static final MediaType TSV_UTF_8 = createConstantUtf8(TEXT_TYPE, "tab-separated-values");
166
167  public static final MediaType VCARD_UTF_8 = createConstantUtf8(TEXT_TYPE, "vcard");
168  public static final MediaType WML_UTF_8 = createConstantUtf8(TEXT_TYPE, "vnd.wap.wml");
169
170  /**
171   * As described in <a href="http://www.ietf.org/rfc/rfc3023.txt">RFC 3023</a>, this constant
172   * ({@code text/xml}) is used for XML documents that are "readable by casual users." {@link
173   * #APPLICATION_XML_UTF_8} is provided for documents that are intended for applications.
174   */
175  public static final MediaType XML_UTF_8 = createConstantUtf8(TEXT_TYPE, "xml");
176
177  /**
178   * As described in <a href="https://w3c.github.io/webvtt/#iana-text-vtt">the VTT spec</a>, this is
179   * used for Web Video Text Tracks (WebVTT) files, used with the HTML5 track element.
180   *
181   * @since 20.0
182   */
183  public static final MediaType VTT_UTF_8 = createConstantUtf8(TEXT_TYPE, "vtt");
184
185  /* image types */
186  public static final MediaType BMP = createConstant(IMAGE_TYPE, "bmp");
187
188  /**
189   * The media type for the <a href="http://en.wikipedia.org/wiki/Camera_Image_File_Format">Canon
190   * Image File Format</a> ({@code crw} files), a widely-used "raw image" format for cameras. It is
191   * found in {@code /etc/mime.types}, e.g. in <a href=
192   * "http://anonscm.debian.org/gitweb/?p=collab-maint/mime-support.git;a=blob;f=mime.types;hb=HEAD"
193   * >Debian 3.48-1</a>.
194   *
195   * @since 15.0
196   */
197  public static final MediaType CRW = createConstant(IMAGE_TYPE, "x-canon-crw");
198
199  public static final MediaType GIF = createConstant(IMAGE_TYPE, "gif");
200  public static final MediaType ICO = createConstant(IMAGE_TYPE, "vnd.microsoft.icon");
201  public static final MediaType JPEG = createConstant(IMAGE_TYPE, "jpeg");
202  public static final MediaType PNG = createConstant(IMAGE_TYPE, "png");
203
204  /**
205   * The media type for the Photoshop File Format ({@code psd} files) as defined by <a
206   * href="http://www.iana.org/assignments/media-types/image/vnd.adobe.photoshop">IANA</a>, and
207   * found in {@code /etc/mime.types}, e.g. <a
208   * href="http://svn.apache.org/repos/asf/httpd/httpd/branches/1.3.x/conf/mime.types"></a> of the
209   * Apache <a href="http://httpd.apache.org/">HTTPD project</a>; for the specification, see <a
210   * href="http://www.adobe.com/devnet-apps/photoshop/fileformatashtml/PhotoshopFileFormats.htm">
211   * Adobe Photoshop Document Format</a> and <a
212   * href="http://en.wikipedia.org/wiki/Adobe_Photoshop#File_format">Wikipedia</a>; this is the
213   * regular output/input of Photoshop (which can also export to various image formats; note that
214   * files with extension "PSB" are in a distinct but related format).
215   *
216   * <p>This is a more recent replacement for the older, experimental type {@code x-photoshop}: <a
217   * href="http://tools.ietf.org/html/rfc2046#section-6">RFC-2046.6</a>.
218   *
219   * @since 15.0
220   */
221  public static final MediaType PSD = createConstant(IMAGE_TYPE, "vnd.adobe.photoshop");
222
223  public static final MediaType SVG_UTF_8 = createConstantUtf8(IMAGE_TYPE, "svg+xml");
224  public static final MediaType TIFF = createConstant(IMAGE_TYPE, "tiff");
225  public static final MediaType WEBP = createConstant(IMAGE_TYPE, "webp");
226
227  /* audio types */
228  public static final MediaType MP4_AUDIO = createConstant(AUDIO_TYPE, "mp4");
229  public static final MediaType MPEG_AUDIO = createConstant(AUDIO_TYPE, "mpeg");
230  public static final MediaType OGG_AUDIO = createConstant(AUDIO_TYPE, "ogg");
231  public static final MediaType WEBM_AUDIO = createConstant(AUDIO_TYPE, "webm");
232
233  /**
234   * Media type for L16 audio, as defined by <a href="https://tools.ietf.org/html/rfc2586">RFC
235   * 2586</a>.
236   *
237   * @since 24.1
238   */
239  public static final MediaType L16_AUDIO = createConstant(AUDIO_TYPE, "l16");
240
241  /**
242   * Media type for L24 audio, as defined by <a href="https://tools.ietf.org/html/rfc3190">RFC
243   * 3190</a>.
244   *
245   * @since 20.0
246   */
247  public static final MediaType L24_AUDIO = createConstant(AUDIO_TYPE, "l24");
248
249  /**
250   * Media type for Basic Audio, as defined by <a
251   * href="http://tools.ietf.org/html/rfc2046#section-4.3">RFC 2046</a>.
252   *
253   * @since 20.0
254   */
255  public static final MediaType BASIC_AUDIO = createConstant(AUDIO_TYPE, "basic");
256
257  /**
258   * Media type for Advanced Audio Coding. For more information, see <a
259   * href="https://en.wikipedia.org/wiki/Advanced_Audio_Coding">Advanced Audio Coding</a>.
260   *
261   * @since 20.0
262   */
263  public static final MediaType AAC_AUDIO = createConstant(AUDIO_TYPE, "aac");
264
265  /**
266   * Media type for Vorbis Audio, as defined by <a href="http://tools.ietf.org/html/rfc5215">RFC
267   * 5215</a>.
268   *
269   * @since 20.0
270   */
271  public static final MediaType VORBIS_AUDIO = createConstant(AUDIO_TYPE, "vorbis");
272
273  /**
274   * Media type for Windows Media Audio. For more information, see <a
275   * href="https://msdn.microsoft.com/en-us/library/windows/desktop/dd562994(v=vs.85).aspx">file
276   * name extensions for Windows Media metafiles</a>.
277   *
278   * @since 20.0
279   */
280  public static final MediaType WMA_AUDIO = createConstant(AUDIO_TYPE, "x-ms-wma");
281
282  /**
283   * Media type for Windows Media metafiles. For more information, see <a
284   * href="https://msdn.microsoft.com/en-us/library/windows/desktop/dd562994(v=vs.85).aspx">file
285   * name extensions for Windows Media metafiles</a>.
286   *
287   * @since 20.0
288   */
289  public static final MediaType WAX_AUDIO = createConstant(AUDIO_TYPE, "x-ms-wax");
290
291  /**
292   * Media type for Real Audio. For more information, see <a
293   * href="http://service.real.com/help/faq/rp8/configrp8win.html">this link</a>.
294   *
295   * @since 20.0
296   */
297  public static final MediaType VND_REAL_AUDIO = createConstant(AUDIO_TYPE, "vnd.rn-realaudio");
298
299  /**
300   * Media type for WAVE format, as defined by <a href="https://tools.ietf.org/html/rfc2361">RFC
301   * 2361</a>.
302   *
303   * @since 20.0
304   */
305  public static final MediaType VND_WAVE_AUDIO = createConstant(AUDIO_TYPE, "vnd.wave");
306
307  /* video types */
308  public static final MediaType MP4_VIDEO = createConstant(VIDEO_TYPE, "mp4");
309  public static final MediaType MPEG_VIDEO = createConstant(VIDEO_TYPE, "mpeg");
310  public static final MediaType OGG_VIDEO = createConstant(VIDEO_TYPE, "ogg");
311  public static final MediaType QUICKTIME = createConstant(VIDEO_TYPE, "quicktime");
312  public static final MediaType WEBM_VIDEO = createConstant(VIDEO_TYPE, "webm");
313  public static final MediaType WMV = createConstant(VIDEO_TYPE, "x-ms-wmv");
314
315  /**
316   * Media type for Flash video. For more information, see <a href=
317   * "http://help.adobe.com/en_US/ActionScript/3.0_ProgrammingAS3/WS5b3ccc516d4fbf351e63e3d118a9b90204-7d48.html"
318   * >this link</a>.
319   *
320   * @since 20.0
321   */
322  public static final MediaType FLV_VIDEO = createConstant(VIDEO_TYPE, "x-flv");
323
324  /**
325   * Media type for the 3GP multimedia container format. For more information, see <a
326   * href="ftp://www.3gpp.org/tsg_sa/TSG_SA/TSGS_23/Docs/PDF/SP-040065.pdf#page=10">3GPP TS
327   * 26.244</a>.
328   *
329   * @since 20.0
330   */
331  public static final MediaType THREE_GPP_VIDEO = createConstant(VIDEO_TYPE, "3gpp");
332
333  /**
334   * Media type for the 3G2 multimedia container format. For more information, see <a
335   * href="http://www.3gpp2.org/Public_html/specs/C.S0050-B_v1.0_070521.pdf#page=16">3GPP2
336   * C.S0050-B</a>.
337   *
338   * @since 20.0
339   */
340  public static final MediaType THREE_GPP2_VIDEO = createConstant(VIDEO_TYPE, "3gpp2");
341
342  /* application types */
343  /**
344   * As described in <a href="http://www.ietf.org/rfc/rfc3023.txt">RFC 3023</a>, this constant
345   * ({@code application/xml}) is used for XML documents that are "unreadable by casual users."
346   * {@link #XML_UTF_8} is provided for documents that may be read by users.
347   */
348  public static final MediaType APPLICATION_XML_UTF_8 = createConstantUtf8(APPLICATION_TYPE, "xml");
349
350  public static final MediaType ATOM_UTF_8 = createConstantUtf8(APPLICATION_TYPE, "atom+xml");
351  public static final MediaType BZIP2 = createConstant(APPLICATION_TYPE, "x-bzip2");
352
353  /**
354   * Media type for <a href="https://www.dartlang.org/articles/embedding-in-html/">dart files</a>.
355   *
356   * @since 19.0
357   */
358  public static final MediaType DART_UTF_8 = createConstantUtf8(APPLICATION_TYPE, "dart");
359
360  /**
361   * Media type for <a href="https://goo.gl/2QoMvg">Apple Passbook</a>.
362   *
363   * @since 19.0
364   */
365  public static final MediaType APPLE_PASSBOOK =
366      createConstant(APPLICATION_TYPE, "vnd.apple.pkpass");
367
368  /**
369   * Media type for <a href="http://en.wikipedia.org/wiki/Embedded_OpenType">Embedded OpenType</a>
370   * fonts. This is <a
371   * href="http://www.iana.org/assignments/media-types/application/vnd.ms-fontobject">registered
372   * </a> with the IANA.
373   *
374   * @since 17.0
375   */
376  public static final MediaType EOT = createConstant(APPLICATION_TYPE, "vnd.ms-fontobject");
377
378  /**
379   * As described in the <a href="http://idpf.org/epub">International Digital Publishing Forum</a>
380   * EPUB is the distribution and interchange format standard for digital publications and
381   * documents. This media type is defined in the <a
382   * href="http://www.idpf.org/epub/30/spec/epub30-ocf.html">EPUB Open Container Format</a>
383   * specification.
384   *
385   * @since 15.0
386   */
387  public static final MediaType EPUB = createConstant(APPLICATION_TYPE, "epub+zip");
388
389  public static final MediaType FORM_DATA =
390      createConstant(APPLICATION_TYPE, "x-www-form-urlencoded");
391
392  /**
393   * As described in <a href="https://www.rsa.com/rsalabs/node.asp?id=2138">PKCS #12: Personal
394   * Information Exchange Syntax Standard</a>, PKCS #12 defines an archive file format for storing
395   * many cryptography objects as a single file.
396   *
397   * @since 15.0
398   */
399  public static final MediaType KEY_ARCHIVE = createConstant(APPLICATION_TYPE, "pkcs12");
400
401  /**
402   * This is a non-standard media type, but is commonly used in serving hosted binary files as it is
403   * <a href="http://code.google.com/p/browsersec/wiki/Part2#Survey_of_content_sniffing_behaviors">
404   * known not to trigger content sniffing in current browsers</a>. It <i>should not</i> be used in
405   * other situations as it is not specified by any RFC and does not appear in the <a
406   * href="http://www.iana.org/assignments/media-types">/IANA MIME Media Types</a> list. Consider
407   * {@link #OCTET_STREAM} for binary data that is not being served to a browser.
408   *
409   * @since 14.0
410   */
411  public static final MediaType APPLICATION_BINARY = createConstant(APPLICATION_TYPE, "binary");
412
413  public static final MediaType GZIP = createConstant(APPLICATION_TYPE, "x-gzip");
414
415  /**
416   * Media type for the <a href="https://tools.ietf.org/html/draft-kelly-json-hal-08#section-3">JSON
417   * Hypertext Application Language (HAL) documents</a>.
418   *
419   * @since 26.0
420   */
421  public static final MediaType HAL_JSON = createConstant(APPLICATION_TYPE, "hal+json");
422
423  /**
424   * <a href="http://www.rfc-editor.org/rfc/rfc4329.txt">RFC 4329</a> declares this to be the
425   * correct media type for JavaScript, but {@link #TEXT_JAVASCRIPT_UTF_8 text/javascript} may be
426   * necessary in certain situations for compatibility.
427   */
428  public static final MediaType JAVASCRIPT_UTF_8 =
429      createConstantUtf8(APPLICATION_TYPE, "javascript");
430
431  public static final MediaType JSON_UTF_8 = createConstantUtf8(APPLICATION_TYPE, "json");
432
433  /**
434   * Media type for the <a href="http://www.w3.org/TR/appmanifest/">Manifest for a web
435   * application</a>.
436   *
437   * @since 19.0
438   */
439  public static final MediaType MANIFEST_JSON_UTF_8 =
440      createConstantUtf8(APPLICATION_TYPE, "manifest+json");
441
442  /**
443   * Media type for <a href="http://www.opengeospatial.org/standards/kml/">OGC KML (Keyhole Markup
444   * Language)</a>.
445   */
446  public static final MediaType KML = createConstant(APPLICATION_TYPE, "vnd.google-earth.kml+xml");
447
448  /**
449   * Media type for <a href="http://www.opengeospatial.org/standards/kml/">OGC KML (Keyhole Markup
450   * Language)</a>, compressed using the ZIP format into KMZ archives.
451   */
452  public static final MediaType KMZ = createConstant(APPLICATION_TYPE, "vnd.google-earth.kmz");
453
454  /** Media type for the <a href="https://tools.ietf.org/html/rfc4155">mbox database format</a>. */
455  public static final MediaType MBOX = createConstant(APPLICATION_TYPE, "mbox");
456
457  /**
458   * Media type for <a href="http://goo.gl/1pGBFm">Apple over-the-air mobile configuration
459   * profiles</a>.
460   *
461   * @since 18.0
462   */
463  public static final MediaType APPLE_MOBILE_CONFIG =
464      createConstant(APPLICATION_TYPE, "x-apple-aspen-config");
465
466  public static final MediaType MICROSOFT_EXCEL = createConstant(APPLICATION_TYPE, "vnd.ms-excel");
467  public static final MediaType MICROSOFT_POWERPOINT =
468      createConstant(APPLICATION_TYPE, "vnd.ms-powerpoint");
469  public static final MediaType MICROSOFT_WORD = createConstant(APPLICATION_TYPE, "msword");
470
471  /**
472   * Media type for WASM applications. For more information see <a
473   * href="https://webassembly.org/">the Web Assembly overview</a>.
474   *
475   * @since 27.0
476   */
477  public static final MediaType WASM_APPLICATION = createConstant(APPLICATION_TYPE, "wasm");
478  /**
479   * Media type for NaCl applications. For more information see <a
480   * href="https://developer.chrome.com/native-client/devguide/coding/application-structure">the
481   * Developer Guide for Native Client Application Structure</a>.
482   *
483   * @since 20.0
484   */
485  public static final MediaType NACL_APPLICATION = createConstant(APPLICATION_TYPE, "x-nacl");
486
487  /**
488   * Media type for NaCl portable applications. For more information see <a
489   * href="https://developer.chrome.com/native-client/devguide/coding/application-structure">the
490   * Developer Guide for Native Client Application Structure</a>.
491   *
492   * @since 20.0
493   */
494  public static final MediaType NACL_PORTABLE_APPLICATION =
495      createConstant(APPLICATION_TYPE, "x-pnacl");
496
497  public static final MediaType OCTET_STREAM = createConstant(APPLICATION_TYPE, "octet-stream");
498
499  public static final MediaType OGG_CONTAINER = createConstant(APPLICATION_TYPE, "ogg");
500  public static final MediaType OOXML_DOCUMENT =
501      createConstant(
502          APPLICATION_TYPE, "vnd.openxmlformats-officedocument.wordprocessingml.document");
503  public static final MediaType OOXML_PRESENTATION =
504      createConstant(
505          APPLICATION_TYPE, "vnd.openxmlformats-officedocument.presentationml.presentation");
506  public static final MediaType OOXML_SHEET =
507      createConstant(APPLICATION_TYPE, "vnd.openxmlformats-officedocument.spreadsheetml.sheet");
508  public static final MediaType OPENDOCUMENT_GRAPHICS =
509      createConstant(APPLICATION_TYPE, "vnd.oasis.opendocument.graphics");
510  public static final MediaType OPENDOCUMENT_PRESENTATION =
511      createConstant(APPLICATION_TYPE, "vnd.oasis.opendocument.presentation");
512  public static final MediaType OPENDOCUMENT_SPREADSHEET =
513      createConstant(APPLICATION_TYPE, "vnd.oasis.opendocument.spreadsheet");
514  public static final MediaType OPENDOCUMENT_TEXT =
515      createConstant(APPLICATION_TYPE, "vnd.oasis.opendocument.text");
516  public static final MediaType PDF = createConstant(APPLICATION_TYPE, "pdf");
517  public static final MediaType POSTSCRIPT = createConstant(APPLICATION_TYPE, "postscript");
518
519  /**
520   * <a href="http://tools.ietf.org/html/draft-rfernando-protocol-buffers-00">Protocol buffers</a>
521   *
522   * @since 15.0
523   */
524  public static final MediaType PROTOBUF = createConstant(APPLICATION_TYPE, "protobuf");
525
526  public static final MediaType RDF_XML_UTF_8 = createConstantUtf8(APPLICATION_TYPE, "rdf+xml");
527  public static final MediaType RTF_UTF_8 = createConstantUtf8(APPLICATION_TYPE, "rtf");
528
529  /**
530   * Media type for SFNT fonts (which includes <a
531   * href="http://en.wikipedia.org/wiki/TrueType/">TrueType</a> and <a
532   * href="http://en.wikipedia.org/wiki/OpenType/">OpenType</a> fonts). This is <a
533   * href="http://www.iana.org/assignments/media-types/application/font-sfnt">registered</a> with
534   * the IANA.
535   *
536   * @since 17.0
537   */
538  public static final MediaType SFNT = createConstant(APPLICATION_TYPE, "font-sfnt");
539
540  public static final MediaType SHOCKWAVE_FLASH =
541      createConstant(APPLICATION_TYPE, "x-shockwave-flash");
542  public static final MediaType SKETCHUP = createConstant(APPLICATION_TYPE, "vnd.sketchup.skp");
543
544  /**
545   * As described in <a href="http://www.ietf.org/rfc/rfc3902.txt">RFC 3902</a>, this constant
546   * ({@code application/soap+xml}) is used to identify SOAP 1.2 message envelopes that have been
547   * serialized with XML 1.0.
548   *
549   * <p>For SOAP 1.1 messages, see {@code XML_UTF_8} per <a
550   * href="http://www.w3.org/TR/2000/NOTE-SOAP-20000508/">W3C Note on Simple Object Access Protocol
551   * (SOAP) 1.1</a>
552   *
553   * @since 20.0
554   */
555  public static final MediaType SOAP_XML_UTF_8 = createConstantUtf8(APPLICATION_TYPE, "soap+xml");
556
557  public static final MediaType TAR = createConstant(APPLICATION_TYPE, "x-tar");
558
559  /**
560   * Media type for the <a href="http://en.wikipedia.org/wiki/Web_Open_Font_Format">Web Open Font
561   * Format</a> (WOFF) <a href="http://www.w3.org/TR/WOFF/">defined</a> by the W3C. This is <a
562   * href="http://www.iana.org/assignments/media-types/application/font-woff">registered</a> with
563   * the IANA.
564   *
565   * @since 17.0
566   */
567  public static final MediaType WOFF = createConstant(APPLICATION_TYPE, "font-woff");
568
569  /**
570   * Media type for the <a href="http://en.wikipedia.org/wiki/Web_Open_Font_Format">Web Open Font
571   * Format</a> (WOFF) version 2 <a href="https://www.w3.org/TR/WOFF2/">defined</a> by the W3C.
572   *
573   * @since 20.0
574   */
575  public static final MediaType WOFF2 = createConstant(APPLICATION_TYPE, "font-woff2");
576
577  public static final MediaType XHTML_UTF_8 = createConstantUtf8(APPLICATION_TYPE, "xhtml+xml");
578
579  /**
580   * Media type for Extensible Resource Descriptors. This is not yet registered with the IANA, but
581   * it is specified by OASIS in the <a
582   * href="http://docs.oasis-open.org/xri/xrd/v1.0/cd02/xrd-1.0-cd02.html">XRD definition</a> and
583   * implemented in projects such as <a href="http://code.google.com/p/webfinger/">WebFinger</a>.
584   */
585  public static final MediaType XRD_UTF_8 = createConstantUtf8(APPLICATION_TYPE, "xrd+xml");
586
587  public static final MediaType ZIP = createConstant(APPLICATION_TYPE, "zip");
588
589  private final String type;
590  private final String subtype;
591  private final ImmutableListMultimap<String, String> parameters;
592
593  @LazyInit private String toString;
594
595  @LazyInit private int hashCode;
596
597  @LazyInit private Optional<Charset> parsedCharset;
598
599  private MediaType(String type, String subtype, ImmutableListMultimap<String, String> parameters) {
600    this.type = type;
601    this.subtype = subtype;
602    this.parameters = parameters;
603  }
604
605  /** Returns the top-level media type. For example, {@code "text"} in {@code "text/plain"}. */
606  public String type() {
607    return type;
608  }
609
610  /** Returns the media subtype. For example, {@code "plain"} in {@code "text/plain"}. */
611  public String subtype() {
612    return subtype;
613  }
614
615  /** Returns a multimap containing the parameters of this media type. */
616  public ImmutableListMultimap<String, String> parameters() {
617    return parameters;
618  }
619
620  private Map<String, ImmutableMultiset<String>> parametersAsMap() {
621    return Maps.transformValues(
622        parameters.asMap(),
623        new Function<Collection<String>, ImmutableMultiset<String>>() {
624          @Override
625          public ImmutableMultiset<String> apply(Collection<String> input) {
626            return ImmutableMultiset.copyOf(input);
627          }
628        });
629  }
630
631  /**
632   * Returns an optional charset for the value of the charset parameter if it is specified.
633   *
634   * @throws IllegalStateException if multiple charset values have been set for this media type
635   * @throws IllegalCharsetNameException if a charset value is present, but illegal
636   * @throws UnsupportedCharsetException if a charset value is present, but no support is available
637   *     in this instance of the Java virtual machine
638   */
639  public Optional<Charset> charset() {
640    // racy single-check idiom, this is safe because Optional is immutable.
641    Optional<Charset> local = parsedCharset;
642    if (local == null) {
643      String value = null;
644      local = Optional.absent();
645      for (String currentValue : parameters.get(CHARSET_ATTRIBUTE)) {
646        if (value == null) {
647          value = currentValue;
648          local = Optional.of(Charset.forName(value));
649        } else if (!value.equals(currentValue)) {
650          throw new IllegalStateException(
651              "Multiple charset values defined: " + value + ", " + currentValue);
652        }
653      }
654      parsedCharset = local;
655    }
656    return local;
657  }
658
659  /**
660   * Returns a new instance with the same type and subtype as this instance, but without any
661   * parameters.
662   */
663  public MediaType withoutParameters() {
664    return parameters.isEmpty() ? this : create(type, subtype);
665  }
666
667  /**
668   * <em>Replaces</em> all parameters with the given parameters.
669   *
670   * @throws IllegalArgumentException if any parameter or value is invalid
671   */
672  public MediaType withParameters(Multimap<String, String> parameters) {
673    return create(type, subtype, parameters);
674  }
675
676  /**
677   * <em>Replaces</em> all parameters with the given attribute with parameters using the given
678   * values. If there are no values, any existing parameters with the given attribute are removed.
679   *
680   * @throws IllegalArgumentException if either {@code attribute} or {@code values} is invalid
681   * @since 24.0
682   */
683  public MediaType withParameters(String attribute, Iterable<String> values) {
684    checkNotNull(attribute);
685    checkNotNull(values);
686    String normalizedAttribute = normalizeToken(attribute);
687    ImmutableListMultimap.Builder<String, String> builder = ImmutableListMultimap.builder();
688    for (Entry<String, String> entry : parameters.entries()) {
689      String key = entry.getKey();
690      if (!normalizedAttribute.equals(key)) {
691        builder.put(key, entry.getValue());
692      }
693    }
694    for (String value : values) {
695      builder.put(normalizedAttribute, normalizeParameterValue(normalizedAttribute, value));
696    }
697    MediaType mediaType = new MediaType(type, subtype, builder.build());
698    // if the attribute isn't charset, we can just inherit the current parsedCharset
699    if (!normalizedAttribute.equals(CHARSET_ATTRIBUTE)) {
700      mediaType.parsedCharset = this.parsedCharset;
701    }
702    // Return one of the constants if the media type is a known type.
703    return MoreObjects.firstNonNull(KNOWN_TYPES.get(mediaType), mediaType);
704  }
705
706  /**
707   * <em>Replaces</em> all parameters with the given attribute with a single parameter with the
708   * given value. If multiple parameters with the same attributes are necessary use {@link
709   * #withParameters(String, Iterable)}. Prefer {@link #withCharset} for setting the {@code charset}
710   * parameter when using a {@link Charset} object.
711   *
712   * @throws IllegalArgumentException if either {@code attribute} or {@code value} is invalid
713   */
714  public MediaType withParameter(String attribute, String value) {
715    return withParameters(attribute, ImmutableSet.of(value));
716  }
717
718  /**
719   * Returns a new instance with the same type and subtype as this instance, with the {@code
720   * charset} parameter set to the {@link Charset#name name} of the given charset. Only one {@code
721   * charset} parameter will be present on the new instance regardless of the number set on this
722   * one.
723   *
724   * <p>If a charset must be specified that is not supported on this JVM (and thus is not
725   * representable as a {@link Charset} instance, use {@link #withParameter}.
726   */
727  public MediaType withCharset(Charset charset) {
728    checkNotNull(charset);
729    MediaType withCharset = withParameter(CHARSET_ATTRIBUTE, charset.name());
730    // precache the charset so we don't need to parse it
731    withCharset.parsedCharset = Optional.of(charset);
732    return withCharset;
733  }
734
735  /** Returns true if either the type or subtype is the wildcard. */
736  public boolean hasWildcard() {
737    return WILDCARD.equals(type) || WILDCARD.equals(subtype);
738  }
739
740  /**
741   * Returns {@code true} if this instance falls within the range (as defined by <a
742   * href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">the HTTP Accept header</a>) given
743   * by the argument according to three criteria:
744   *
745   * <ol>
746   *   <li>The type of the argument is the wildcard or equal to the type of this instance.
747   *   <li>The subtype of the argument is the wildcard or equal to the subtype of this instance.
748   *   <li>All of the parameters present in the argument are present in this instance.
749   * </ol>
750   *
751   * <p>For example:
752   *
753   * <pre>{@code
754   * PLAIN_TEXT_UTF_8.is(PLAIN_TEXT_UTF_8) // true
755   * PLAIN_TEXT_UTF_8.is(HTML_UTF_8) // false
756   * PLAIN_TEXT_UTF_8.is(ANY_TYPE) // true
757   * PLAIN_TEXT_UTF_8.is(ANY_TEXT_TYPE) // true
758   * PLAIN_TEXT_UTF_8.is(ANY_IMAGE_TYPE) // false
759   * PLAIN_TEXT_UTF_8.is(ANY_TEXT_TYPE.withCharset(UTF_8)) // true
760   * PLAIN_TEXT_UTF_8.withoutParameters().is(ANY_TEXT_TYPE.withCharset(UTF_8)) // false
761   * PLAIN_TEXT_UTF_8.is(ANY_TEXT_TYPE.withCharset(UTF_16)) // false
762   * }</pre>
763   *
764   * <p>Note that while it is possible to have the same parameter declared multiple times within a
765   * media type this method does not consider the number of occurrences of a parameter. For example,
766   * {@code "text/plain; charset=UTF-8"} satisfies {@code "text/plain; charset=UTF-8;
767   * charset=UTF-8"}.
768   */
769  public boolean is(MediaType mediaTypeRange) {
770    return (mediaTypeRange.type.equals(WILDCARD) || mediaTypeRange.type.equals(this.type))
771        && (mediaTypeRange.subtype.equals(WILDCARD) || mediaTypeRange.subtype.equals(this.subtype))
772        && this.parameters.entries().containsAll(mediaTypeRange.parameters.entries());
773  }
774
775  /**
776   * Creates a new media type with the given type and subtype.
777   *
778   * @throws IllegalArgumentException if type or subtype is invalid or if a wildcard is used for the
779   *     type, but not the subtype.
780   */
781  public static MediaType create(String type, String subtype) {
782    MediaType mediaType = create(type, subtype, ImmutableListMultimap.<String, String>of());
783    mediaType.parsedCharset = Optional.absent();
784    return mediaType;
785  }
786
787  private static MediaType create(
788      String type, String subtype, Multimap<String, String> parameters) {
789    checkNotNull(type);
790    checkNotNull(subtype);
791    checkNotNull(parameters);
792    String normalizedType = normalizeToken(type);
793    String normalizedSubtype = normalizeToken(subtype);
794    checkArgument(
795        !WILDCARD.equals(normalizedType) || WILDCARD.equals(normalizedSubtype),
796        "A wildcard type cannot be used with a non-wildcard subtype");
797    ImmutableListMultimap.Builder<String, String> builder = ImmutableListMultimap.builder();
798    for (Entry<String, String> entry : parameters.entries()) {
799      String attribute = normalizeToken(entry.getKey());
800      builder.put(attribute, normalizeParameterValue(attribute, entry.getValue()));
801    }
802    MediaType mediaType = new MediaType(normalizedType, normalizedSubtype, builder.build());
803    // Return one of the constants if the media type is a known type.
804    return MoreObjects.firstNonNull(KNOWN_TYPES.get(mediaType), mediaType);
805  }
806
807  /**
808   * Creates a media type with the "application" type and the given subtype.
809   *
810   * @throws IllegalArgumentException if subtype is invalid
811   */
812  static MediaType createApplicationType(String subtype) {
813    return create(APPLICATION_TYPE, subtype);
814  }
815
816  /**
817   * Creates a media type with the "audio" type and the given subtype.
818   *
819   * @throws IllegalArgumentException if subtype is invalid
820   */
821  static MediaType createAudioType(String subtype) {
822    return create(AUDIO_TYPE, subtype);
823  }
824
825  /**
826   * Creates a media type with the "image" type and the given subtype.
827   *
828   * @throws IllegalArgumentException if subtype is invalid
829   */
830  static MediaType createImageType(String subtype) {
831    return create(IMAGE_TYPE, subtype);
832  }
833
834  /**
835   * Creates a media type with the "text" type and the given subtype.
836   *
837   * @throws IllegalArgumentException if subtype is invalid
838   */
839  static MediaType createTextType(String subtype) {
840    return create(TEXT_TYPE, subtype);
841  }
842
843  /**
844   * Creates a media type with the "video" type and the given subtype.
845   *
846   * @throws IllegalArgumentException if subtype is invalid
847   */
848  static MediaType createVideoType(String subtype) {
849    return create(VIDEO_TYPE, subtype);
850  }
851
852  private static String normalizeToken(String token) {
853    checkArgument(TOKEN_MATCHER.matchesAllOf(token));
854    return Ascii.toLowerCase(token);
855  }
856
857  private static String normalizeParameterValue(String attribute, String value) {
858    return CHARSET_ATTRIBUTE.equals(attribute) ? Ascii.toLowerCase(value) : value;
859  }
860
861  /**
862   * Parses a media type from its string representation.
863   *
864   * @throws IllegalArgumentException if the input is not parsable
865   */
866  public static MediaType parse(String input) {
867    checkNotNull(input);
868    Tokenizer tokenizer = new Tokenizer(input);
869    try {
870      String type = tokenizer.consumeToken(TOKEN_MATCHER);
871      tokenizer.consumeCharacter('/');
872      String subtype = tokenizer.consumeToken(TOKEN_MATCHER);
873      ImmutableListMultimap.Builder<String, String> parameters = ImmutableListMultimap.builder();
874      while (tokenizer.hasMore()) {
875        tokenizer.consumeTokenIfPresent(LINEAR_WHITE_SPACE);
876        tokenizer.consumeCharacter(';');
877        tokenizer.consumeTokenIfPresent(LINEAR_WHITE_SPACE);
878        String attribute = tokenizer.consumeToken(TOKEN_MATCHER);
879        tokenizer.consumeCharacter('=');
880        final String value;
881        if ('"' == tokenizer.previewChar()) {
882          tokenizer.consumeCharacter('"');
883          StringBuilder valueBuilder = new StringBuilder();
884          while ('"' != tokenizer.previewChar()) {
885            if ('\\' == tokenizer.previewChar()) {
886              tokenizer.consumeCharacter('\\');
887              valueBuilder.append(tokenizer.consumeCharacter(ascii()));
888            } else {
889              valueBuilder.append(tokenizer.consumeToken(QUOTED_TEXT_MATCHER));
890            }
891          }
892          value = valueBuilder.toString();
893          tokenizer.consumeCharacter('"');
894        } else {
895          value = tokenizer.consumeToken(TOKEN_MATCHER);
896        }
897        parameters.put(attribute, value);
898      }
899      return create(type, subtype, parameters.build());
900    } catch (IllegalStateException e) {
901      throw new IllegalArgumentException("Could not parse '" + input + "'", e);
902    }
903  }
904
905  private static final class Tokenizer {
906    final String input;
907    int position = 0;
908
909    Tokenizer(String input) {
910      this.input = input;
911    }
912
913    String consumeTokenIfPresent(CharMatcher matcher) {
914      checkState(hasMore());
915      int startPosition = position;
916      position = matcher.negate().indexIn(input, startPosition);
917      return hasMore() ? input.substring(startPosition, position) : input.substring(startPosition);
918    }
919
920    String consumeToken(CharMatcher matcher) {
921      int startPosition = position;
922      String token = consumeTokenIfPresent(matcher);
923      checkState(position != startPosition);
924      return token;
925    }
926
927    char consumeCharacter(CharMatcher matcher) {
928      checkState(hasMore());
929      char c = previewChar();
930      checkState(matcher.matches(c));
931      position++;
932      return c;
933    }
934
935    char consumeCharacter(char c) {
936      checkState(hasMore());
937      checkState(previewChar() == c);
938      position++;
939      return c;
940    }
941
942    char previewChar() {
943      checkState(hasMore());
944      return input.charAt(position);
945    }
946
947    boolean hasMore() {
948      return (position >= 0) && (position < input.length());
949    }
950  }
951
952  @Override
953  public boolean equals(@Nullable Object obj) {
954    if (obj == this) {
955      return true;
956    } else if (obj instanceof MediaType) {
957      MediaType that = (MediaType) obj;
958      return this.type.equals(that.type)
959          && this.subtype.equals(that.subtype)
960          // compare parameters regardless of order
961          && this.parametersAsMap().equals(that.parametersAsMap());
962    } else {
963      return false;
964    }
965  }
966
967  @Override
968  public int hashCode() {
969    // racy single-check idiom
970    int h = hashCode;
971    if (h == 0) {
972      h = Objects.hashCode(type, subtype, parametersAsMap());
973      hashCode = h;
974    }
975    return h;
976  }
977
978  private static final MapJoiner PARAMETER_JOINER = Joiner.on("; ").withKeyValueSeparator("=");
979
980  /**
981   * Returns the string representation of this media type in the format described in <a
982   * href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>.
983   */
984  @Override
985  public String toString() {
986    // racy single-check idiom, safe because String is immutable
987    String result = toString;
988    if (result == null) {
989      result = computeToString();
990      toString = result;
991    }
992    return result;
993  }
994
995  private String computeToString() {
996    StringBuilder builder = new StringBuilder().append(type).append('/').append(subtype);
997    if (!parameters.isEmpty()) {
998      builder.append("; ");
999      Multimap<String, String> quotedParameters =
1000          Multimaps.transformValues(
1001              parameters,
1002              new Function<String, String>() {
1003                @Override
1004                public String apply(String value) {
1005                  return TOKEN_MATCHER.matchesAllOf(value) ? value : escapeAndQuote(value);
1006                }
1007              });
1008      PARAMETER_JOINER.appendTo(builder, quotedParameters.entries());
1009    }
1010    return builder.toString();
1011  }
1012
1013  private static String escapeAndQuote(String value) {
1014    StringBuilder escaped = new StringBuilder(value.length() + 16).append('"');
1015    for (int i = 0; i < value.length(); i++) {
1016      char ch = value.charAt(i);
1017      if (ch == '\r' || ch == '\\' || ch == '"') {
1018        escaped.append('\\');
1019      }
1020      escaped.append(ch);
1021    }
1022    return escaped.append('"').toString();
1023  }
1024}