Provide immutable MediaType class

[GoogleCodeExporter]

While the Java Mail API provides a content type class, it still has some 
drawbacks. Some are that it's not immutable (think constants) and it lacks a 
(static) constructor to create one just from primary and sub type as separate 
arguments without specifying a(n empty) list of parameters.

Also, HTTP uses MIME/content types as well, but those projects might not want 
to depend on an e-mail-related package.

My personal requirements:
- immutability
- Allow explicit addressing of the charset both on construction and as a getter 
(not just having to find it by key in the list of parameters).
- Provide matching of the primary type, the sub type, parameters, and 
combinations of all of those (say, primary type and sub type and charset).
- Maybe support matchers like "text/*", i.e. a wildcard for the sub type (that 
case might be sufficient). However, comparison with/without parameters (or just 
a selection of those) might require some further thinking.
- Handle case (in)sensivity as appropriate. There are different requirements 
for the parameters of certain MIME types on how to interpret their keys and 
values regarding that¹.
- Provide conversion methods from/to `ContentType` (Java Mail API).
- Have a thoughtful implementation of `equals`. I think everything should be 
compared, including parameters.

¹) From my own investigation:
- According to RFC 2045, section 5.1, the primary type, subtype, and parameter 
names must always be matched case insensitive.
- According to RFC 2046, section 4.1.2, the value of the charset parameter 
(implicit default: US-ASCII) is case insensitive, but the values of other 
parameters might not be.

I have implemented an immutable content type myself, but so far only included 
specifically the charset parameter of text types, but no other parameters (e.g. 
filename; not to confuse with the parameter of the `Content-Disposition: 
attachment` header).

Also, a builder-style approach might be useful to optionally add parameters as 
needed before the immutable instance is created.

On a related note, the Guava class that contains HTTP header keys is quite 
nice. Maybe something similar for common content types would make sense? In 
that case, the content type class' API should allow for composition of 
pre-defined primary/sub type combinations (plaintext, HTML, CSV, JSON, 
octet-stream, PDF, images etc.) with parameters to fit specific needs.

Original issue reported on code.google.com by j...@nwsnet.de on 14 Dec 2011 at 2:08

[GoogleCodeExporter]

We've got something like this internally...we'll work on open sourcing it in 
the next month or so.

Original comment by kak@google.com on 14 Dec 2011 at 11:44

• Added labels: Type-Enhancement

[GoogleCodeExporter]

Yay! I'm really looking forward to this, it would help me a lot.

Regarding the separate charset parameter, I came to the conclusion that it 
might be unnecessary as long as there is a constant for the parameter name 
available (similar to `HttpHeaders`, IIRC). A method `Optional<String> 
findParameterValue(String parameterName)` should work well.

Original comment by j...@nwsnet.de on 15 Dec 2011 at 9:13

[GoogleCodeExporter]

Wow, we have almost exactly what you suggested ;-)

public Optional<Charset> charset();

I'm going to discuss this at our weekly API review meeting and see if we can 
get this out sooner rather than later.

Original comment by kak@google.com on 15 Dec 2011 at 5:51

[GoogleCodeExporter]

That'd be excellent, thanks!

Original comment by j...@nwsnet.de on 15 Dec 2011 at 11:22

[GoogleCodeExporter]

We'll get MediaType added to git very soon.

Original comment by kevinb@google.com on 10 Jan 2012 at 11:43

• Changed title: Provide immutable MediaType class
• Added labels: Milestone-Release12

[GoogleCodeExporter]

Sweet! Thanks for the update.

Original comment by j...@nwsnet.de on 11 Jan 2012 at 10:42

[GoogleCodeExporter]

How close is this to arrival in git? I'd really love to take a look its API. :)

Original comment by j...@nwsnet.de on 26 Jan 2012 at 1:33

[GoogleCodeExporter]

It's "close" to hitting git...I'll see what we can do to get it out sometime 
soon.

Original comment by kak@google.com on 26 Jan 2012 at 4:52

• Added labels: Package-Net

[GoogleCodeExporter]

(Re-assigning to gak@ since he's the primary author and the newest member of 
our team!)

FYI, this will get pushed out to HEAD tomorrow morning (and subsequently 
released in Guava 12).  Please take a look at the API and give us any feedback 
once it hits the repo.

Original comment by kurt.kluever on 15 Feb 2012 at 6:04

[GoogleCodeExporter]

I'm pretty sure that we've covered most of the feature requests in the original 
bug, so I'm going to mark this fixed.  Let us know if anybody has an more 
issues/requests and keep in mind that this class is still @Beta, so things may 
change.

Original comment by gak@google.com on 14 Mar 2012 at 4:39

• Changed state: Fixed

[GoogleCodeExporter]

It is good to have this class in guava, but I was surprised it is missing 
"application/xml" type. Is it by purpose? It's really strange that such an 
often used type has been left out.

Original comment by hus...@gmail.com on 30 Dec 2012 at 12:53

[GoogleCodeExporter]

It wasn't left out for any reason other than that we hadn't had any request for 
it.  It seems that the majority of our users internally had been using text/xml 
over application/xml, so it just hadn't come up.  I'll be happy to add it 
though.

Original comment by gak@google.com on 2 Jan 2013 at 6:30

[GoogleCodeExporter]

Will be very appreciated, since it is one of the required mime types in Google 
Cloud Storage: 
https://developers.google.com/storage/docs/developer-guide#overview

Thanks

Original comment by hus...@gmail.com on 3 Jan 2013 at 12:47

[GoogleCodeExporter]

This issue has been migrated to GitHub.

It can be found at https://github.com/google/guava/issues/<id>

Original comment by cgdecker@google.com on 1 Nov 2014 at 4:15

• Added labels: MigratedToGitHub

[GoogleCodeExporter]

Original comment by cgdecker@google.com on 3 Nov 2014 at 9:09

• Added labels: Restrict-AddIssueComment-Commit