io.jsonwebtoken.Header Maven / Gradle / Ivy
/*
* Copyright (C) 2014 jsonwebtoken.io
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package io.jsonwebtoken;
import java.util.Map;
/**
* A JWT JOSE header.
*
* This is ultimately a JSON map and any values can be added to it, but JWT JOSE standard names are provided as
* type-safe getters and setters for convenience.
*
* Because this interface extends {@code Map<String, Object>}, if you would like to add your own properties,
* you simply use map methods, for example:
*
*
* header.{@link Map#put(Object, Object) put}("headerParamName", "headerParamValue");
*
*
* Creation
*
* It is easiest to create a {@code Header} instance by calling one of the
* {@link Jwts#header() JWTs.header()} factory methods.
*
* @since 0.1
*/
public interface Header> extends Map {
/** JWT {@code Type} (typ) value: "JWT" */
public static final String JWT_TYPE = "JWT";
/** JWT {@code Type} header parameter name: "typ" */
public static final String TYPE = "typ";
/** JWT {@code Content Type} header parameter name: "cty" */
public static final String CONTENT_TYPE = "cty";
/** JWT {@code Compression Algorithm} header parameter name: "zip" */
public static final String COMPRESSION_ALGORITHM = "zip";
/** JJWT legacy/deprecated compression algorithm header parameter name: "calg"
* @deprecated use {@link #COMPRESSION_ALGORITHM} instead. */
@Deprecated
public static final String DEPRECATED_COMPRESSION_ALGORITHM = "calg";
/**
* Returns the
* typ (type) header value or {@code null} if not present.
*
* @return the {@code typ} header value or {@code null} if not present.
*/
String getType();
/**
* Sets the JWT
* typ (Type) header value. A {@code null} value will remove the property from the JSON map.
*
* @param typ the JWT JOSE {@code typ} header value or {@code null} to remove the property from the JSON map.
* @return the {@code Header} instance for method chaining.
*/
T setType(String typ);
/**
* Returns the
* cty (Content Type) header value or {@code null} if not present.
*
* In the normal case where nested signing or encryption operations are not employed (i.e. a compact
* serialization JWT), the use of this header parameter is NOT RECOMMENDED. In the case that nested
* signing or encryption is employed, this Header Parameter MUST be present; in this case, the value MUST be
* {@code JWT}, to indicate that a Nested JWT is carried in this JWT. While media type names are not
* case-sensitive, it is RECOMMENDED that {@code JWT} always be spelled using uppercase characters for
* compatibility with legacy implementations. See
* JWT Appendix A.2 for
* an example of a Nested JWT.
*
* @return the {@code typ} header parameter value or {@code null} if not present.
*/
String getContentType();
/**
* Sets the JWT
* cty (Content Type) header parameter value. A {@code null} value will remove the property from
* the JSON map.
*
* In the normal case where nested signing or encryption operations are not employed (i.e. a compact
* serialization JWT), the use of this header parameter is NOT RECOMMENDED. In the case that nested
* signing or encryption is employed, this Header Parameter MUST be present; in this case, the value MUST be
* {@code JWT}, to indicate that a Nested JWT is carried in this JWT. While media type names are not
* case-sensitive, it is RECOMMENDED that {@code JWT} always be spelled using uppercase characters for
* compatibility with legacy implementations. See
* JWT Appendix A.2 for
* an example of a Nested JWT.
*
* @param cty the JWT JOSE {@code cty} header value or {@code null} to remove the property from the JSON map.
* @return the {@code Header} instance for method chaining.
*/
T setContentType(String cty);
/**
* Returns the JWT zip (Compression Algorithm) header value or {@code null} if not present.
*
* @return the {@code zip} header parameter value or {@code null} if not present.
* @since 0.6.0
*/
String getCompressionAlgorithm();
/**
* Sets the JWT zip (Compression Algorithm) header parameter value. A {@code null} value will remove
* the property from the JSON map.
*
* The compression algorithm is NOT part of the JWT specification
* and must be used carefully since, is not expected that other libraries (including previous versions of this one)
* be able to deserialize a compressed JTW body correctly.
*
* @param zip the JWT compression algorithm {@code zip} value or {@code null} to remove the property from the JSON map.
* @return the {@code Header} instance for method chaining.
* @since 0.6.0
*/
T setCompressionAlgorithm(String zip);
}