jjwt v0.2 Release Notes
-
๐ More convenient Claims building
๐ This release adds convenience methods to the
JwtBuilder
interface so you can set claims directly on the builder without having to create a separate Claims instance/builder, reducing the amount of code you have to write. For example, this:Claims claims = Jwts.claims().setSubject("Joe"); String compactJwt = Jwts.builder().setClaims(claims).signWith(HS256, key).compact();
can now be written as:
String compactJwt = Jwts.builder().setSubject("Joe").signWith(HS256, key).compact();
๐ฐ A Claims instance based on the specified claims will be created and set as the JWT's payload automatically.
Type-safe handling for JWT and JWS with generics
The following < 0.2 code produced a JWT as expected:
Jwt jwt = Jwts.parser().setSigningKey(key).parse(compact);
๐ But you couldn't easily determine if the
jwt
was aJWT
orJWS
instance or if the body was aClaims
instance or a plaintextString
without resorting to a bunch of yuckyinstanceof
checks. In 0.2, we introduce theJwtHandler
when you don't know the exact format of the compact JWT string ahead of time, and parsing convenience methods when you do.JwtHandler
๐ If you do not know the format of the compact JWT string at the time you try to parse it, you can determine what type it is after parsing by providing a
JwtHandler
instance to theJwtParser
with the newparse(String compactJwt, JwtHandler handler)
method. For example:T returnVal = Jwts.parser().setSigningKey(key).parse(compact, new JwtHandler<T>() { @Override public T onPlaintextJwt(Jwt<Header, String> jwt) { //the JWT parsed was an unsigned plaintext JWT //inspect it, then return an instance of T (see returnVal above) } @Override public T onClaimsJwt(Jwt<Header, Claims> jwt) { //the JWT parsed was an unsigned Claims JWT //inspect it, then return an instance of T (see returnVal above) } @Override public T onPlaintextJws(Jws<String> jws) { //the JWT parsed was a signed plaintext JWS //inspect it, then return an instance of T (see returnVal above) } @Override public T onClaimsJws(Jws<Claims> jws) { //the JWT parsed was a signed Claims JWS //inspect it, then return an instance of T (see returnVal above) } });
๐ Of course, if you know you'll only have to parse a subset of the above, you can use the
JwtHandlerAdapter
and implement only the methods you need. For example:T returnVal = Jwts.parser().setSigningKey(key).parse(plaintextJwt, new JwtHandlerAdapter<Jwt<Header, T>>() { @Override public T onPlaintextJws(Jws<String> jws) { //the JWT parsed was a signed plaintext JWS //inspect it, then return an instance of T (see returnVal above) } @Override public T onClaimsJws(Jws<Claims> jws) { //the JWT parsed was a signed Claims JWS //inspect it, then return an instance of T (see returnVal above) } });
๐ Known Type convenience parse methods
๐ If, unlike above, you are confident of the compact string format and know which type of JWT or JWS it will produce, you can just use one of the 4 new convenience parsing methods to get exactly the type of JWT or JWS you know exists. For example:
//for a known plaintext jwt string: Jwt<Header,String> jwt = Jwts.parser().parsePlaintextJwt(compact); //for a known Claims JWT string: Jwt<Header,Claims> jwt = Jwts.parser().parseClaimsJwt(compact); //for a known signed plaintext JWT (aka a plaintext JWS): Jws<String> jws = Jwts.parser().setSigningKey(key).parsePlaintextJws(compact); //for a known signed Claims JWT (aka a Claims JWS): Jws<Claims> jws = Jwts.parser().setSigningKey(key).parseClaimsJws(compact);