io.jsonwebtoken.Claims 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.Date;
import java.util.Map;

/**
 * A JWT Claims set.
 *
 * This is ultimately a JSON map and any values can be added to it, but JWT 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:
 *
 *  * claims.{@link Map#put(Object, Object) put}("someKey", "someValue");
 * 
 *
 * Creation
 *
 * It is easiest to create a {@code Claims} instance by calling one of the
 * {@link Jwts#claims() JWTs.claims()} factory methods.
 *
 * @since 0.1
 */
public interface Claims extends Map, ClaimsMutator {

    /** JWT {@code Issuer} claims parameter name: "iss" */
    public static final String ISSUER = "iss";

    /** JWT {@code Subject} claims parameter name: "sub" */
    public static final String SUBJECT = "sub";

    /** JWT {@code Audience} claims parameter name: "aud" */
    public static final String AUDIENCE = "aud";

    /** JWT {@code Expiration} claims parameter name: "exp" */
    public static final String EXPIRATION = "exp";

    /** JWT {@code Not Before} claims parameter name: "nbf" */
    public static final String NOT_BEFORE = "nbf";

    /** JWT {@code Issued At} claims parameter name: "iat" */
    public static final String ISSUED_AT = "iat";

    /** JWT {@code JWT ID} claims parameter name: "jti" */
    public static final String ID = "jti";

    /**
     * Returns the JWT 
     * iss (issuer) value or {@code null} if not present.
     *
     * @return the JWT {@code iss} value or {@code null} if not present.
     */
    String getIssuer();

    /**
     * {@inheritDoc}
     */
    @Override //only for better/targeted JavaDoc
    Claims setIssuer(String iss);

    /**
     * Returns the JWT 
     * sub (subject) value or {@code null} if not present.
     *
     * @return the JWT {@code sub} value or {@code null} if not present.
     */
    String getSubject();

    /**
     * {@inheritDoc}
     */
    @Override //only for better/targeted JavaDoc
    Claims setSubject(String sub);

    /**
     * Returns the JWT 
     * aud (audience) value or {@code null} if not present.
     *
     * @return the JWT {@code aud} value or {@code null} if not present.
     */
    String getAudience();

    /**
     * {@inheritDoc}
     */
    @Override //only for better/targeted JavaDoc
    Claims setAudience(String aud);

    /**
     * Returns the JWT 
     * exp (expiration) timestamp or {@code null} if not present.
     *
     * A JWT obtained after this timestamp should not be used.
     *
     * @return the JWT {@code exp} value or {@code null} if not present.
     */
    Date getExpiration();

    /**
     * {@inheritDoc}
     */
    @Override //only for better/targeted JavaDoc
    Claims setExpiration(Date exp);

    /**
     * Returns the JWT 
     * nbf (not before) timestamp or {@code null} if not present.
     *
     * A JWT obtained before this timestamp should not be used.
     *
     * @return the JWT {@code nbf} value or {@code null} if not present.
     */
    Date getNotBefore();

    /**
     * {@inheritDoc}
     */
    @Override //only for better/targeted JavaDoc
    Claims setNotBefore(Date nbf);

    /**
     * Returns the JWT 
     * iat (issued at) timestamp or {@code null} if not present.
     *
     * If present, this value is the timestamp when the JWT was created.
     *
     * @return the JWT {@code nbf} value or {@code null} if not present.
     */
    Date getIssuedAt();

    /**
     * {@inheritDoc}
     */
    @Override //only for better/targeted JavaDoc
    Claims setIssuedAt(Date iat);

    /**
     * Returns the JWTs 
     * jti (JWT ID) value or {@code null} if not present.
     *
     * This value is a CaSe-SenSiTiVe unique identifier for the JWT. If available, this value is expected to 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.
     *
     * @return the JWT {@code jti} value or {@code null} if not present.
     */
    String getId();

    /**
     * {@inheritDoc}
     */
    @Override //only for better/targeted JavaDoc
    Claims setId(String jti);

     T get(String claimName, Class requiredType);
}