acscommons.io.jsonwebtoken.Header Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of acs-aem-commons-bundle Show documentation
Core ACS AEM Commons OSGi Bundle. Includes commons utilities.
There is a newer version: 6.6.0
Show newest version
/*
 * 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 acscommons.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.
     */
    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.
     * @since 0.6.0
     */
    T setCompressionAlgorithm(String zip);

}