Add support for custom type deserialization with Jackson

[bdemers]

Adds new constructor to JacksonDeserializer(Map<String, Class> claimTypeMap), which will enable later calls Claims.get("key", CustomType.class) to work as expectd

Fixes: #369

TODO:

• When we are happy with this, I'll start a 0.11.0-README branch and add a note about how to use this feature. Docs: Adds section to README covering custom object parsing #500

[bdemers]

NOTE: this sits on top of fix-split-package to avoid merge conflicts (as JacksonDeserializer was moved in that branch)

[coveralls]

Coverage remained the same at 100.0% when pulling c0470e1 on issue-369 into e20883e on fix-split-package.

[lhazlewood]

Are we going to create the Maps.of utility method? (would reside, presumably, in io.jsonwebtoken.lang.Maps).

[bdemers]

Yeah, easy enough to add. I was thinking of recommending just using the Java 11 Map.of, but I know many of us will be on 8 for a while yet.

[lhazlewood]

Shouldn't this be a builder of sorts? Or in addition?

For example, I consider this a lot nicer than a bunch of parameters in a single method:

Maps.put(key1, value1).put(key2, value2).put(key3, value3).build()

(for example).

Thoughts?

[bdemers]

I'm not against it that 🤔 I just went the Java 11-ish route of Map.of(),
I've done something things with a .put() in the past, my concern is Map returns the value type on a put, so that might be confusing?

I will say, I like the chained method look better than the overloaded method, mostly because it seems DRYer?

I'm not sure if Map.of() will ever see common use (at least for a while)

[lhazlewood]

ah, right - instead of put, then maybe of or with or and.

[lhazlewood]

I like this:

Maps.of(key1, value1).and(key2, value2).and(key3, value3)...

Maps.of creates a builder instance, puts the first key/value and returns the builder. And just adds the key/value and returns the builder. Looks nice and fluent.

Thoughts?

[bdemers]

I like that!

[lhazlewood]

I think we should add one more sentence at the end of this paragraph:

If using Jackson, you can specify custom claim POJO types as described in <url-here>.

Where <url-here> is of course the section in the documentation that explains how to do this that you're presumably writing in #500

Since I would think Jackson will be the most widely used parser.

Thoughts?

[lhazlewood]

Can we add some documentation here that it uses a new ObjectMapper instance?

For example, after the current documentation:

<p>
Because custom type parsing requires modifying Jackson {@code ObjectMapper} state, this 
constructor creates a new internal {@code ObjectMapper} instance and customizes it to support the 
specified {@code claimTypeMap}.  This ensures that JJWT parsing behavior does not unexpectedly 
modify the state of another application-specific {@code ObjectMapper}.
</p>
<p>
If you would like to use your own {@code ObjectMapper} instance that also supports custom types for 
JWT {@code Claims}, you will need to first customize your {@code ObjectMapper} instance by registering 
your custom types and then use the {@link JacksonDeserializer(ObjectMapper) } constructor instead.
</p>

Based on this, I wonder if we might want to make MappedTypeDeserializer a dedicated independent public class in the jjwt-jackson module so that users can use it on their own ObjectMapper instance (e.g. they might have customized pretty printing, but still want custom type registration, etc). That class would document how to use it in the class JavaDoc based on what we've done, e.g.:

MappedTypeDeserializer typeDeserializer = new MappedTypeDeserializer(typeMap);
SimpleModule module = new SimpleModule();
module.addDeserializer(Object.class, typeDeserializer);
objectMapper.registerModule(module);

All of this would help address the confusion I had (for example) around type customization on an application-wide deserializer, as well as provide an out-of-the-box solution for people that wanted to customize their own ObjectMapper.

Thoughts?

[bdemers]

Great doc suggestion

I thought about extracting MappedTypeDeserializer out, but I worry it might cause a maintenance headache trying to cover more parsing edge cases (when combined with other Jackson configurations). My personal pref would be to hold off unless people ask for it (YAGNI?). It's really easy to extract that class later, but if we make invalid assumptions now, it is harder to retract them.

That was my thinking anyway, though I could be missing some of the benefits of sharing an ObjectMapper instance?

[lhazlewood]

I worry it might cause a maintenance headache trying to cover more parsing edge cases (when combined with other Jackson configurations)

I was thinking the current implementation would be the only one we'd support, and if that doesn't meet one's needs, they can just do it the manual approach or implement their own JsonSerializer. At least they'd see easily how to do it themselves since understanding how that works is most of the difficulty, and our example gets them out of the weeds.

That said, I see value with leaving it private and the YAGNI argument. I guess I'm on the fence 50/50 and would be happy with whatever you choose, so feel free ;)

[bdemers]

Rebased manually (to merge in the split package change)