https://github.com/eclipse-ee4j/jaxrs-api: Jakarta RESTful Web Services (Eclipse Foundation) 
/*
 * Copyright (c) 2010, 2019 Oracle and/or its affiliates. All rights reserved.
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License v. 2.0, which is available at
 * http://www.eclipse.org/legal/epl-2.0.
 *
 * This Source Code may also be made available under the following Secondary
 * Licenses when the conditions for such availability set forth in the
 * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
 * version 2 with the GNU Classpath Exception, which is available at
 * https://www.gnu.org/software/classpath/license.html.
 *
 * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 */

package jakarta.ws.rs.core;

import java.util.Date;

import jakarta.ws.rs.ext.RuntimeDelegate;
import jakarta.ws.rs.ext.RuntimeDelegate.HeaderDelegate;


Used to create a new HTTP cookie, transferred in a response.

Author:Paul Sandoz, Marc Hadley
See Also:
Since:1.0
/**
 * Used to create a new HTTP cookie, transferred in a response.
 *
 * @author Paul Sandoz
 * @author Marc Hadley
 * @see <a href="http://www.ietf.org/rfc/rfc2109.txt">IETF RFC 2109</a>
 * @since 1.0
 */
public class NewCookie extends Cookie {

    
Specifies that the cookie expires with the current application/browser session.

/**
     * Specifies that the cookie expires with the current application/browser session.
     */
    public static final int DEFAULT_MAX_AGE = -1;

    
Deprecated:This field will be removed in a future version. See https://github.com/eclipse-ee4j/jaxrs-api/issues/607
/**
     * @deprecated This field will be removed in a future version. See https://github.com/eclipse-ee4j/jaxrs-api/issues/607
     */
    @Deprecated
    private static final HeaderDelegate<NewCookie> delegate = RuntimeDelegate.getInstance().createHeaderDelegate(NewCookie.class);

    private final String comment;
    private final int maxAge;
    private final Date expiry;
    private final boolean secure;
    private final boolean httpOnly;

    
Create a new instance.

Params:
  • name – the name of the cookie.
  • value – the value of the cookie.
Throws:
/**
     * Create a new instance.
     *
     * @param name the name of the cookie.
     * @param value the value of the cookie.
     * @throws IllegalArgumentException if name is {@code null}.
     */
    public NewCookie(final String name, final String value) {
        this(name, value, null, null, DEFAULT_VERSION, null, DEFAULT_MAX_AGE, null, false, false);
    }

    
Create a new instance.

Params:
  • name – the name of the cookie.
  • value – the value of the cookie.
  • path – the URI path for which the cookie is valid.
  • domain – the host domain for which the cookie is valid.
  • comment – the comment.
  • maxAge – the maximum age of the cookie in seconds.
  • secure – specifies whether the cookie will only be sent over a secure connection.
Throws:
/**
     * Create a new instance.
     *
     * @param name the name of the cookie.
     * @param value the value of the cookie.
     * @param path the URI path for which the cookie is valid.
     * @param domain the host domain for which the cookie is valid.
     * @param comment the comment.
     * @param maxAge the maximum age of the cookie in seconds.
     * @param secure specifies whether the cookie will only be sent over a secure connection.
     * @throws IllegalArgumentException if name is {@code null}.
     */
    public NewCookie(final String name,
            final String value,
            final String path,
            final String domain,
            final String comment,
            final int maxAge,
            final boolean secure) {
        this(name, value, path, domain, DEFAULT_VERSION, comment, maxAge, null, secure, false);
    }

    
Create a new instance.

Params:
  • name – the name of the cookie.
  • value – the value of the cookie.
  • path – the URI path for which the cookie is valid.
  • domain – the host domain for which the cookie is valid.
  • comment – the comment.
  • maxAge – the maximum age of the cookie in seconds.
  • secure – specifies whether the cookie will only be sent over a secure connection.
  • httpOnly – if true make the cookie HTTP only, i.e. only visible as part of an HTTP request.
Throws:
Since:2.0
/**
     * Create a new instance.
     *
     * @param name the name of the cookie.
     * @param value the value of the cookie.
     * @param path the URI path for which the cookie is valid.
     * @param domain the host domain for which the cookie is valid.
     * @param comment the comment.
     * @param maxAge the maximum age of the cookie in seconds.
     * @param secure specifies whether the cookie will only be sent over a secure connection.
     * @param httpOnly if {@code true} make the cookie HTTP only, i.e. only visible as part of an HTTP request.
     * @throws IllegalArgumentException if name is {@code null}.
     * @since 2.0
     */
    public NewCookie(final String name,
            final String value,
            final String path,
            final String domain,
            final String comment,
            final int maxAge,
            final boolean secure,
            final boolean httpOnly) {
        this(name, value, path, domain, DEFAULT_VERSION, comment, maxAge, null, secure, httpOnly);
    }

    
Create a new instance.

Params:
  • name – the name of the cookie
  • value – the value of the cookie
  • path – the URI path for which the cookie is valid
  • domain – the host domain for which the cookie is valid
  • version – the version of the specification to which the cookie complies
  • comment – the comment
  • maxAge – the maximum age of the cookie in seconds
  • secure – specifies whether the cookie will only be sent over a secure connection
Throws:
/**
     * Create a new instance.
     *
     * @param name the name of the cookie
     * @param value the value of the cookie
     * @param path the URI path for which the cookie is valid
     * @param domain the host domain for which the cookie is valid
     * @param version the version of the specification to which the cookie complies
     * @param comment the comment
     * @param maxAge the maximum age of the cookie in seconds
     * @param secure specifies whether the cookie will only be sent over a secure connection
     * @throws IllegalArgumentException if name is {@code null}.
     */
    public NewCookie(final String name,
            final String value,
            final String path,
            final String domain,
            final int version,
            final String comment,
            final int maxAge,
            final boolean secure) {
        this(name, value, path, domain, version, comment, maxAge, null, secure, false);
    }

    
Create a new instance.

Params:
  • name – the name of the cookie
  • value – the value of the cookie
  • path – the URI path for which the cookie is valid
  • domain – the host domain for which the cookie is valid
  • version – the version of the specification to which the cookie complies
  • comment – the comment
  • maxAge – the maximum age of the cookie in seconds
  • expiry – the cookie expiry date.
  • secure – specifies whether the cookie will only be sent over a secure connection
  • httpOnly – if true make the cookie HTTP only, i.e. only visible as part of an HTTP request.
Throws:
Since:2.0
/**
     * Create a new instance.
     *
     * @param name the name of the cookie
     * @param value the value of the cookie
     * @param path the URI path for which the cookie is valid
     * @param domain the host domain for which the cookie is valid
     * @param version the version of the specification to which the cookie complies
     * @param comment the comment
     * @param maxAge the maximum age of the cookie in seconds
     * @param expiry the cookie expiry date.
     * @param secure specifies whether the cookie will only be sent over a secure connection
     * @param httpOnly if {@code true} make the cookie HTTP only, i.e. only visible as part of an HTTP request.
     * @throws IllegalArgumentException if name is {@code null}.
     * @since 2.0
     */
    public NewCookie(final String name,
            final String value,
            final String path,
            final String domain,
            final int version,
            final String comment,
            final int maxAge,
            final Date expiry,
            final boolean secure,
            final boolean httpOnly) {
        super(name, value, path, domain, version);
        this.comment = comment;
        this.maxAge = maxAge;
        this.expiry = expiry;
        this.secure = secure;
        this.httpOnly = httpOnly;
    }

    
Create a new instance copying the information in the supplied cookie.

Params:
  • cookie – the cookie to clone.
Throws:
/**
     * Create a new instance copying the information in the supplied cookie.
     *
     * @param cookie the cookie to clone.
     * @throws IllegalArgumentException if cookie is {@code null}.
     */
    public NewCookie(final Cookie cookie) {
        this(cookie, null, DEFAULT_MAX_AGE, null, false, false);
    }

    
Create a new instance supplementing the information in the supplied cookie.

Params:
  • cookie – the cookie to clone.
  • comment – the comment.
  • maxAge – the maximum age of the cookie in seconds.
  • secure – specifies whether the cookie will only be sent over a secure connection.
Throws:
/**
     * Create a new instance supplementing the information in the supplied cookie.
     *
     * @param cookie the cookie to clone.
     * @param comment the comment.
     * @param maxAge the maximum age of the cookie in seconds.
     * @param secure specifies whether the cookie will only be sent over a secure connection.
     * @throws IllegalArgumentException if cookie is {@code null}.
     */
    public NewCookie(final Cookie cookie, final String comment, final int maxAge, final boolean secure) {
        this(cookie, comment, maxAge, null, secure, false);
    }

    
Create a new instance supplementing the information in the supplied cookie.

Params:
  • cookie – the cookie to clone.
  • comment – the comment.
  • maxAge – the maximum age of the cookie in seconds.
  • expiry – the cookie expiry date.
  • secure – specifies whether the cookie will only be sent over a secure connection.
  • httpOnly – if true make the cookie HTTP only, i.e. only visible as part of an HTTP request.
Throws:
Since:2.0
/**
     * Create a new instance supplementing the information in the supplied cookie.
     *
     * @param cookie the cookie to clone.
     * @param comment the comment.
     * @param maxAge the maximum age of the cookie in seconds.
     * @param expiry the cookie expiry date.
     * @param secure specifies whether the cookie will only be sent over a secure connection.
     * @param httpOnly if {@code true} make the cookie HTTP only, i.e. only visible as part of an HTTP request.
     * @throws IllegalArgumentException if cookie is {@code null}.
     * @since 2.0
     */
    public NewCookie(final Cookie cookie, final String comment, final int maxAge, final Date expiry, final boolean secure, final boolean httpOnly) {
        super(cookie == null ? null : cookie.getName(),
                cookie == null ? null : cookie.getValue(),
                cookie == null ? null : cookie.getPath(),
                cookie == null ? null : cookie.getDomain(),
                cookie == null ? Cookie.DEFAULT_VERSION : cookie.getVersion());
        this.comment = comment;
        this.maxAge = maxAge;
        this.expiry = expiry;
        this.secure = secure;
        this.httpOnly = httpOnly;
    }

    
Creates a new instance of NewCookie by parsing the supplied string.

Params:
  • value – the cookie string.
Throws:
Returns:the newly created NewCookie.
Deprecated:This method will be removed in a future version. Please use
RuntimeDelegate.getInstance().createHeaderDelegate(NewCookie.class).fromString(value) instead.
/**
     * Creates a new instance of NewCookie by parsing the supplied string.
     *
     * @param value the cookie string.
     * @return the newly created {@code NewCookie}.
     * @throws IllegalArgumentException if the supplied string cannot be parsed or is {@code null}.
     * @deprecated This method will be removed in a future version. Please use
     * RuntimeDelegate.getInstance().createHeaderDelegate(NewCookie.class).fromString(value) instead.
     */
    @Deprecated
    public static NewCookie valueOf(final String value) {
        return delegate.fromString(value);
    }

    
Get the comment associated with the cookie.

Returns:the comment or null if none set
/**
     * Get the comment associated with the cookie.
     *
     * @return the comment or null if none set
     */
    public String getComment() {
        return comment;
    }

    
Get the maximum age of the the cookie in seconds. Cookies older than the maximum age are discarded. A cookie can be unset by sending a new cookie with maximum age of 0 since it will overwrite any existing cookie and then be immediately discarded. The default value of -1 indicates that the cookie will be discarded at the end of the browser/application session. 
 Note that it is recommended to use Max-Age to control cookie expiration, however some browsers do not understand Max-Age, in which case setting getExpiry() Expires} parameter may be necessary. 


See Also:
Returns:the maximum age in seconds.
/**
     * Get the maximum age of the the cookie in seconds. Cookies older than the maximum age are discarded. A cookie can be
     * unset by sending a new cookie with maximum age of 0 since it will overwrite any existing cookie and then be
     * immediately discarded. The default value of {@code -1} indicates that the cookie will be discarded at the end of the
     * browser/application session.
     * <p>
     * Note that it is recommended to use {@code Max-Age} to control cookie expiration, however some browsers do not
     * understand {@code Max-Age}, in which case setting {@link #getExpiry()} Expires} parameter may be necessary.
     * </p>
     *
     * @return the maximum age in seconds.
     * @see #getExpiry()
     */
    public int getMaxAge() {
        return maxAge;
    }

    
Get the cookie expiry date. Cookies whose expiry date has passed are discarded. A cookie can be unset by setting a
new cookie with an expiry date in the past, typically the lowest possible date that can be set.

 Note that it is recommended to use Max-Age to control cookie expiration, however some browsers do not understand Max-Age, in which case setting Expires parameter may be necessary. 


See Also:
Returns:cookie expiry date or null if no expiry date was set.
Since:2.0
/**
     * Get the cookie expiry date. Cookies whose expiry date has passed are discarded. A cookie can be unset by setting a
     * new cookie with an expiry date in the past, typically the lowest possible date that can be set.
     * <p>
     * Note that it is recommended to use {@link #getMaxAge() Max-Age} to control cookie expiration, however some browsers
     * do not understand {@code Max-Age}, in which case setting {@code Expires} parameter may be necessary.
     * </p>
     *
     * @return cookie expiry date or {@code null} if no expiry date was set.
     * @see #getMaxAge()
     * @since 2.0
     */
    public Date getExpiry() {
        return expiry;
    }

    
Whether the cookie will only be sent over a secure connection. Defaults to false. 
Returns:true if the cookie will only be sent over a secure connection, false otherwise.
/**
     * Whether the cookie will only be sent over a secure connection. Defaults to {@code false}.
     *
     * @return {@code true} if the cookie will only be sent over a secure connection, {@code false} otherwise.
     */
    public boolean isSecure() {
        return secure;
    }

    
Returns true if this cookie contains the HttpOnly attribute. This means that the cookie should not be accessible to scripting engines, like javascript. 
Returns:true if this cookie should be considered http only, false otherwise.
Since:2.0
/**
     * Returns {@code true} if this cookie contains the {@code HttpOnly} attribute. This means that the cookie should not be
     * accessible to scripting engines, like javascript.
     *
     * @return {@code true} if this cookie should be considered http only, {@code false} otherwise.
     * @since 2.0
     */
    public boolean isHttpOnly() {
        return httpOnly;
    }

    
Obtain a new instance of a Cookie with the same name, value, path, domain and version as this NewCookie. This method can be used to obtain an object that can be compared for equality with another Cookie; since a Cookie will never compare equal to a NewCookie. 
Returns:a Cookie
/**
     * Obtain a new instance of a {@link Cookie} with the same name, value, path, domain and version as this
     * {@code NewCookie}. This method can be used to obtain an object that can be compared for equality with another
     * {@code Cookie}; since a {@code Cookie} will never compare equal to a {@code NewCookie}.
     *
     * @return a {@link Cookie}
     */
    public Cookie toCookie() {
        return new Cookie(this.getName(), this.getValue(), this.getPath(),
                this.getDomain(), this.getVersion());
    }

    
Convert the cookie to a string suitable for use as the value of the corresponding HTTP header.

Returns:a stringified cookie.
Deprecated:The format of the toString() method is subject to change in a future version. Please use
RuntimeDelegate.getInstance().createHeaderDelegate(NewCookie.class).toString(value) instead if you rely on the format
of this method.
/**
     * Convert the cookie to a string suitable for use as the value of the corresponding HTTP header.
     *
     * @return a stringified cookie.
     * @deprecated The format of the toString() method is subject to change in a future version. Please use
     * RuntimeDelegate.getInstance().createHeaderDelegate(NewCookie.class).toString(value) instead if you rely on the format
     * of this method.
     */
    @Override
    @Deprecated
    public String toString() {
        return delegate.toString(this);
    }

    
Generate a hash code by hashing all of the properties.

Returns:the hash code.
/**
     * Generate a hash code by hashing all of the properties.
     *
     * @return the hash code.
     */
    @Override
    public int hashCode() {
        int hash = super.hashCode();
        hash = 59 * hash + (this.comment != null ? this.comment.hashCode() : 0);
        hash = 59 * hash + this.maxAge;
        hash = 59 + hash + (this.expiry != null ? this.expiry.hashCode() : 0);
        hash = 59 * hash + (this.secure ? 1 : 0);
        hash = 59 * hash + (this.httpOnly ? 1 : 0);
        return hash;
    }

    
Compare for equality. Use toCookie() to compare a NewCookie to a Cookie considering only the common properties. 
Params:
  • obj – the object to compare to
Returns:true if the object is a NewCookie with the same value for all properties, false otherwise.
/**
     * Compare for equality. Use {@link #toCookie()} to compare a {@code NewCookie} to a {@code Cookie} considering only the
     * common properties.
     *
     * @param obj the object to compare to
     * @return true if the object is a {@code NewCookie} with the same value for all properties, false otherwise.
     */
    @SuppressWarnings({ "StringEquality", "RedundantIfStatement" })
    @Override
    public boolean equals(final Object obj) {
        if (obj == null) {
            return false;
        }
        if (getClass() != obj.getClass()) {
            return false;
        }
        final NewCookie other = (NewCookie) obj;
        if (this.getName() != other.getName() && (this.getName() == null || !this.getName().equals(other.getName()))) {
            return false;
        }
        if (this.getValue() != other.getValue() && (this.getValue() == null || !this.getValue().equals(other.getValue()))) {
            return false;
        }
        if (this.getVersion() != other.getVersion()) {
            return false;
        }
        if (this.getPath() != other.getPath() && (this.getPath() == null || !this.getPath().equals(other.getPath()))) {
            return false;
        }
        if (this.getDomain() != other.getDomain() && (this.getDomain() == null || !this.getDomain().equals(other.getDomain()))) {
            return false;
        }
        if (this.comment != other.comment && (this.comment == null || !this.comment.equals(other.comment))) {
            return false;
        }
        if (this.maxAge != other.maxAge) {
            return false;
        }

        if (this.expiry != other.expiry && (this.expiry == null || !this.expiry.equals(other.expiry))) {
            return false;
        }

        if (this.secure != other.secure) {
            return false;
        }
        if (this.httpOnly != other.httpOnly) {
            return false;
        }
        return true;
    }
}