io.jsonwebtoken

Interface JwtBuilder

All Superinterfaces:

ClaimsMutator<JwtBuilder>

All Known Implementing Classes:

DefaultJwtBuilder

public interface JwtBuilder
extends ClaimsMutator<JwtBuilder>

A builder for constructing JWTs.

Since:

0.1

Method Summary

Modifier and Type	Method and Description
JwtBuilder	addClaims(Map<String,Object> claims) Adds all given name/value pairs to the JSON Claims in the payload.
JwtBuilder	claim(String name, Object value) Sets a custom JWT Claims parameter value.
String	compact() Actually builds the JWT and serializes it to a compact, URL-safe string according to the JWT Compact Serialization rules.
JwtBuilder	compressWith(CompressionCodec codec) Compresses the JWT body using the specified CompressionCodec.
JwtBuilder	setAudience(String aud) Sets the JWT Claims aud (audience) value.
JwtBuilder	setClaims(Claims claims) Sets the JWT payload to be a JSON Claims instance.
JwtBuilder	setClaims(Map<String,Object> claims) Sets the JWT payload to be a JSON Claims instance populated by the specified name/value pairs.
JwtBuilder	setExpiration(Date exp) Sets the JWT Claims exp (expiration) value.
JwtBuilder	setHeader(Header header) Sets (and replaces) any existing header with the specified header.
JwtBuilder	setHeader(Map<String,Object> header) Sets (and replaces) any existing header with the specified header.
JwtBuilder	setHeaderParam(String name, Object value) Applies the specified name/value pair to the header.
JwtBuilder	setHeaderParams(Map<String,Object> params) Applies the specified name/value pairs to the header.
JwtBuilder	setId(String jti) Sets the JWT Claims jti (JWT ID) value.
JwtBuilder	setIssuedAt(Date iat) Sets the JWT Claims iat (issued at) value.
JwtBuilder	setIssuer(String iss) Sets the JWT Claims iss (issuer) value.
JwtBuilder	setNotBefore(Date nbf) Sets the JWT Claims nbf (not before) value.
JwtBuilder	setPayload(String payload) Sets the JWT's payload to be a plaintext (non-JSON) string.
JwtBuilder	setSubject(String sub) Sets the JWT Claims sub (subject) value.
JwtBuilder	signWith(SignatureAlgorithm alg, byte[] secretKey) Signs the constructed JWT using the specified algorithm with the specified key, producing a JWS.
JwtBuilder	signWith(SignatureAlgorithm alg, Key key) Signs the constructed JWT using the specified algorithm with the specified key, producing a JWS.
JwtBuilder	signWith(SignatureAlgorithm alg, String base64EncodedSecretKey) Signs the constructed JWT using the specified algorithm with the specified key, producing a JWS.

Method Detail

setHeader

JwtBuilder setHeader(Header header)

Sets (and replaces) any existing header with the specified header. If you do not want to replace the existing header and only want to append to it, use the setHeaderParams(java.util.Map) method instead.

Parameters:

header - the header to set (and potentially replace any existing header).

Returns:

the builder for method chaining.

setHeader

JwtBuilder setHeader(Map<String,Object> header)

Sets (and replaces) any existing header with the specified header. If you do not want to replace the existing header and only want to append to it, use the setHeaderParams(java.util.Map) method instead.

Parameters:

header - the header to set (and potentially replace any existing header).

Returns:

the builder for method chaining.

setHeaderParams

JwtBuilder setHeaderParams(Map<String,Object> params)

Applies the specified name/value pairs to the header. If a header does not yet exist at the time this method is called, one will be created automatically before applying the name/value pairs.

Parameters:

params - the header name/value pairs to append to the header.

Returns:

the builder for method chaining.

setHeaderParam

JwtBuilder setHeaderParam(String name,
                          Object value)

Applies the specified name/value pair to the header. If a header does not yet exist at the time this method is called, one will be created automatically before applying the name/value pair.

Parameters:

name - the header parameter name

value - the header parameter value

Returns:

the builder for method chaining.

setPayload

JwtBuilder setPayload(String payload)

Sets the JWT's payload to be a plaintext (non-JSON) string. If you want the JWT body to be JSON, use the setClaims(Claims) or setClaims(java.util.Map) methods instead.

The payload and claims properties are mutually exclusive - only one of the two may be used.

Parameters:

payload - the plaintext (non-JSON) string that will be the body of the JWT.

Returns:

the builder for method chaining.

setClaims

JwtBuilder setClaims(Claims claims)

Sets the JWT payload to be a JSON Claims instance. If you do not want the JWT body to be JSON and instead want it to be a plaintext string, use the setPayload(String) method instead.

The payload and claims properties are mutually exclusive - only one of the two may be used.

Parameters:

claims - the JWT claims to be set as the JWT body.

Returns:

the builder for method chaining.

setClaims

JwtBuilder setClaims(Map<String,Object> claims)

Sets the JWT payload to be a JSON Claims instance populated by the specified name/value pairs. If you do not want the JWT body to be JSON and instead want it to be a plaintext string, use the setPayload(String) method instead.

The payload* and claims* properties are mutually exclusive - only one of the two may be used.

Parameters:

claims - the JWT claims to be set as the JWT body.

Returns:

the builder for method chaining.

addClaims

JwtBuilder addClaims(Map<String,Object> claims)

Adds all given name/value pairs to the JSON Claims in the payload. If a Claims instance does not yet exist at the time this method is called, one will be created automatically before applying the name/value pairs.

The payload and claims properties are mutually exclusive - only one of the two may be used.

Parameters:

claims - the JWT claims to be added to the JWT body.

Returns:

the builder for method chaining.

Since:

0.8

setIssuer

JwtBuilder setIssuer(String iss)

Sets the JWT Claims iss (issuer) value. A null value will remove the property from the Claims.

This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims issuer field with the specified value. This allows you to write code like this:

 String jwt = Jwts.builder().setIssuer("Joe").compact();
 

instead of this:

 Claims claims = Jwts.claims().setIssuer("Joe");
 String jwt = Jwts.builder().setClaims(claims).compact();
 

if desired.

Specified by:

setIssuer in interface ClaimsMutator<JwtBuilder>

Parameters:

iss - the JWT iss value or null to remove the property from the Claims map.

Returns:

the builder instance for method chaining.

Since:

0.2

setSubject

JwtBuilder setSubject(String sub)

Sets the JWT Claims sub (subject) value. A null value will remove the property from the Claims.

This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims subject field with the specified value. This allows you to write code like this:

 String jwt = Jwts.builder().setSubject("Me").compact();
 

instead of this:

 Claims claims = Jwts.claims().setSubject("Me");
 String jwt = Jwts.builder().setClaims(claims).compact();
 

if desired.

Specified by:

setSubject in interface ClaimsMutator<JwtBuilder>

Parameters:

sub - the JWT sub value or null to remove the property from the Claims map.

Returns:

the builder instance for method chaining.

Since:

0.2

setAudience

JwtBuilder setAudience(String aud)

Sets the JWT Claims aud (audience) value. A null value will remove the property from the Claims.

This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims audience field with the specified value. This allows you to write code like this:

 String jwt = Jwts.builder().setAudience("You").compact();
 

instead of this:

 Claims claims = Jwts.claims().setSubject("You");
 String jwt = Jwts.builder().setClaims(claims).compact();
 

if desired.

Specified by:

setAudience in interface ClaimsMutator<JwtBuilder>

Parameters:

aud - the JWT aud value or null to remove the property from the Claims map.

Returns:

the builder instance for method chaining.

Since:

0.2

setExpiration

JwtBuilder setExpiration(Date exp)

Sets the JWT Claims exp (expiration) value. A null value will remove the property from the Claims.

A JWT obtained after this timestamp should not be used.

This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims expiration field with the specified value. This allows you to write code like this:

 String jwt = Jwts.builder().setExpiration(new Date(System.currentTimeMillis() + 3600000)).compact();
 

instead of this:

 Claims claims = Jwts.claims().setExpiration(new Date(System.currentTimeMillis() + 3600000));
 String jwt = Jwts.builder().setClaims(claims).compact();
 

if desired.

Specified by:

setExpiration in interface ClaimsMutator<JwtBuilder>

Parameters:

exp - the JWT exp value or null to remove the property from the Claims map.

Returns:

the builder instance for method chaining.

Since:

0.2

setNotBefore

JwtBuilder setNotBefore(Date nbf)

Sets the JWT Claims nbf (not before) value. A null value will remove the property from the Claims.

A JWT obtained before this timestamp should not be used.

This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims notBefore field with the specified value. This allows you to write code like this:

 String jwt = Jwts.builder().setNotBefore(new Date()).compact();
 

instead of this:

 Claims claims = Jwts.claims().setNotBefore(new Date());
 String jwt = Jwts.builder().setClaims(claims).compact();
 

if desired.

Specified by:

setNotBefore in interface ClaimsMutator<JwtBuilder>

Parameters:

nbf - the JWT nbf value or null to remove the property from the Claims map.

Returns:

the builder instance for method chaining.

Since:

0.2

setIssuedAt

JwtBuilder setIssuedAt(Date iat)

Sets the JWT Claims iat (issued at) value. A null value will remove the property from the Claims.

The value is the timestamp when the JWT was created.

This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims issuedAt field with the specified value. This allows you to write code like this:

 String jwt = Jwts.builder().setIssuedAt(new Date()).compact();
 

instead of this:

 Claims claims = Jwts.claims().setIssuedAt(new Date());
 String jwt = Jwts.builder().setClaims(claims).compact();
 

if desired.

Specified by:

setIssuedAt in interface ClaimsMutator<JwtBuilder>

Parameters:

iat - the JWT iat value or null to remove the property from the Claims map.

Returns:

the builder instance for method chaining.

Since:

0.2

setId

JwtBuilder setId(String jti)

Sets the JWT Claims jti (JWT ID) value. A null value will remove the property from the Claims.

The value is a CaSe-SenSiTiVe unique identifier for the JWT. If specified, this value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object. The ID can be used to prevent the JWT from being replayed.

This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims id field with the specified value. This allows you to write code like this:

 String jwt = Jwts.builder().setId(UUID.randomUUID().toString()).compact();
 

instead of this:

 Claims claims = Jwts.claims().setIssuedAt(UUID.randomUUID().toString());
 String jwt = Jwts.builder().setClaims(claims).compact();
 

if desired.

Specified by:

setId in interface ClaimsMutator<JwtBuilder>

Parameters:

jti - the JWT jti (id) value or null to remove the property from the Claims map.

Returns:

the builder instance for method chaining.

Since:

0.2

claim

JwtBuilder claim(String name,
                 Object value)

Sets a custom JWT Claims parameter value. A null value will remove the property from the Claims.

This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the named property on the Claims instance using the Claims put method. This allows you to write code like this:

 String jwt = Jwts.builder().claim("aName", "aValue").compact();
 

instead of this:

 Claims claims = Jwts.claims().put("aName", "aValue");
 String jwt = Jwts.builder().setClaims(claims).compact();
 

if desired.

Parameters:

name - the JWT Claims property name

value - the value to set for the specified Claims property name

Returns:

the builder instance for method chaining.

Since:

0.2

signWith

JwtBuilder signWith(SignatureAlgorithm alg,
                    byte[] secretKey)

Signs the constructed JWT using the specified algorithm with the specified key, producing a JWS.

Parameters:

alg - the JWS algorithm to use to digitally sign the JWT, thereby producing a JWS.

secretKey - the algorithm-specific signing key to use to digitally sign the JWT.

Returns:

the builder for method chaining.

signWith

JwtBuilder signWith(SignatureAlgorithm alg,
                    String base64EncodedSecretKey)

Signs the constructed JWT using the specified algorithm with the specified key, producing a JWS.

This is a convenience method: the string argument is first BASE64-decoded to a byte array and this resulting byte array is used to invoke signWith(SignatureAlgorithm, byte[]).

Parameters:

alg - the JWS algorithm to use to digitally sign the JWT, thereby producing a JWS.

base64EncodedSecretKey - the BASE64-encoded algorithm-specific signing key to use to digitally sign the JWT.

Returns:

the builder for method chaining.

signWith

JwtBuilder signWith(SignatureAlgorithm alg,
                    Key key)

Signs the constructed JWT using the specified algorithm with the specified key, producing a JWS.

Parameters:

alg - the JWS algorithm to use to digitally sign the JWT, thereby producing a JWS.

key - the algorithm-specific signing key to use to digitally sign the JWT.

Returns:

the builder for method chaining.

compressWith

JwtBuilder compressWith(CompressionCodec codec)

Compresses the JWT body using the specified CompressionCodec.

If your compact JWTs are large, and you want to reduce their total size during network transmission, this can be useful. For example, when embedding JWTs in URLs, some browsers may not support URLs longer than a certain length. Using compression can help ensure the compact JWT fits within that length. However, NOTE:

Compatibility Warning

The JWT family of specifications defines compression only for JWE (Json Web Encryption) tokens. Even so, JJWT will also support compression for JWS tokens as well if you choose to use it. However, be aware that if you use compression when creating a JWS token, other libraries may not be able to parse that JWS token. When using compression for JWS tokens, be sure that that all parties accessing the JWS token support compression for JWS.

Compression when creating JWE tokens however should be universally accepted for any library that supports JWE.

Parameters:

codec - implementation of the CompressionCodec to be used.

Returns:

the builder for method chaining.

Since:

0.6.0

See Also:

CompressionCodecs

compact

String compact()

Actually builds the JWT and serializes it to a compact, URL-safe string according to the JWT Compact Serialization rules.

Returns:

A compact URL-safe JWT string.