JwtParser custom validators

[lhazlewood]

The current JwtParser interface at the time of this issue's creation has mutator methods that enable validation of various claims.

The current require* methods only enforce that the claim exists and is exactly equal to a specified value. While sufficient for many use cases, this is not robust enough to handle many other validations that might be suitable for an application. For example, applications may want to enforce that a claim:

• Simply exists, regardless of its value
• Exists but isn't null
• Exists and equals an exact value
• Exists and matches a particular value
• Exists and is greater than or less than a particular value
• Maybe exists or not, but if it does, adheres to some particular requirement
• etc...

Because of this variability, this issue is being created to track the work required to introduce a new method (or methods) to specify custom validators. For example:

validate(String claimName, Predicate<Optional<T>> condition): - claims key may or may not exist and the Optional.isPresent will indicate existence. Further, null vs non null can be evaluated.

This is likely to be the 'core' validate method for any given claim. We may add additional convenience methods like the following:

requirePresent(String claimName) - only guarantees the map key exists. Value may be null or any other value.
requirePresent(String claimName, Predicate<T> condition) - guarantees map key exists. Only if key exists will the condition be evaluated. If key doesn't exist, validation still succeeds, but the condition is not evaluated.
require(String claimName, Predicate<T> condition) - guarantees map value exists and is not null before evaluating condition. If missing or null, throw an exception during parsing.

(or similar).

If they exist, they'll likely call the validate(String claimName, Predicate<Optional<T>> condition core method.

Design on all of these methods are still up in the air, but this should be a good starting point.

Also, sometimes validation might require inspection of more than one claim, e.g.

enforceClaims(Predicate<Claims> condition)

(or similar).

Additionally, a set of out-of-the-box Predicates should be available to simplify things for people, e.g.

Validators.exists() returns a Predicate<Optional<T>> that returns true if and only if the optional value .isPresent(), false otherwise.

Other potential Validators.* static methods:

• notNull
• isNull
• not (does not equal)
• ... ?

Note that these methods imply Java 8 lambdas, but that's not strictly necessary. It would save a lot of work/effort however if we could use lambdas for this. Given that's already core to most JDK applications, it'd be a hard choice to create our own similar interfaces to simulate lambdas, and that just doesn't sound appealing.

Implementation note: Based on #473 , these methods should be added only to the JwtParserBuilder API and not the existing JwtParser API to enforce correct API usage semantics compatible with the 1.0 release.

[lhazlewood]

We might want to allow disabling key length validation per #521. This violates the specification, so I don't know how I feel about that, especially if #493 gives an alternative to accomplish the same thing if the user really wants to do this. In other words #493 makes it possible, but it wouldn't be glaringly easy/obvious by just looking at or using a fluent validator API (which I think is a good thing).