/*
 * Copyright (c) 2011-2019 Contributors to the Eclipse Foundation
 *
 * This program and the accompanying materials are made available under the
 * terms of the Eclipse Public License 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
 * which is available at https://www.apache.org/licenses/LICENSE-2.0.
 *
 * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
 */

package io.vertx.core.http;

import io.vertx.codegen.annotations.Fluent;
import io.vertx.codegen.annotations.Nullable;
import io.vertx.codegen.annotations.VertxGen;
import io.vertx.core.http.impl.CookieImpl;

Represents an HTTP Cookie.

All cookies must have a name and a value and can optionally have other fields set such as path, domain, etc.
/**
 * Represents an HTTP Cookie.
 * <p>
 * All cookies must have a name and a value and can optionally have other fields set such as path, domain, etc.
 */
@VertxGen
public interface Cookie {

  
Create a new cookie
Params:
name –  the name of the cookie
value –  the cookie value
Returns:
the cookie/**
   * Create a new cookie
   * @param name  the name of the cookie
   * @param value  the cookie value
   * @return the cookie
   */
  static Cookie cookie(String name, String value) {
    return new CookieImpl(name, value);
  }

  
Returns:
the name of this cookie/**
   * @return the name of this cookie
   */
  String getName();

  
Returns:
the value of this cookie/**
   * @return the value of this cookie
   */
  String getValue();

  
Sets the value of this cookie
Params:
value – The value to set
Returns:
a reference to this, so the API can be used fluently/**
   * Sets the value of this cookie
   *
   * @param value The value to set
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  Cookie setValue(String value);

  
Sets the domain of this cookie
Params:
domain – The domain to use
Returns:
a reference to this, so the API can be used fluently/**
   * Sets the domain of this cookie
   *
   * @param domain The domain to use
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  Cookie setDomain(@Nullable String domain);

  
Returns:
 the domain for the cookie/**
   * @return  the domain for the cookie
   */
  @Nullable
  String getDomain();

  
Sets the path of this cookie.
Params:
path – The path to use for this cookie
Returns:
a reference to this, so the API can be used fluently/**
   * Sets the path of this cookie.
   *
   * @param path The path to use for this cookie
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  Cookie setPath(@Nullable String path);

  
Returns:
the path for this cookie/**
   *
   * @return the path for this cookie
   */
  @Nullable
  String getPath();

  
Sets the maximum age of this cookie in seconds. If an age of 0 is specified, this cookie will be automatically removed by browser because it will expire immediately. If Long.MIN_VALUE is specified, this cookie will be removed when the browser is closed. If you don't set this the cookie will be a session cookie and be removed when the browser is closed. 
Params:
maxAge – The maximum age of this cookie in seconds/**
   * Sets the maximum age of this cookie in seconds.
   * If an age of {@code 0} is specified, this cookie will be
   * automatically removed by browser because it will expire immediately.
   * If {@link Long#MIN_VALUE} is specified, this cookie will be removed when the
   * browser is closed.
   * If you don't set this the cookie will be a session cookie and be removed when the browser is closed.
   *
   * @param maxAge The maximum age of this cookie in seconds
   */
  @Fluent
  Cookie setMaxAge(long maxAge);

  
Sets the security getStatus of this cookie
Params:
secure – True if this cookie is to be secure, otherwise false
Returns:
a reference to this, so the API can be used fluently/**
   * Sets the security getStatus of this cookie
   *
   * @param secure True if this cookie is to be secure, otherwise false
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  Cookie setSecure(boolean secure);

  
Returns:
the security status of this cookie/**
   * @return the security status of this cookie
   */
  boolean isSecure();

  
Determines if this cookie is HTTP only.
If set to true, this cookie cannot be accessed by a client
side script. However, this works only if the browser supports it.
For for information, please look
here.
Params:
httpOnly – True if the cookie is HTTP only, otherwise false./**
   * Determines if this cookie is HTTP only.
   * If set to true, this cookie cannot be accessed by a client
   * side script. However, this works only if the browser supports it.
   * For for information, please look
   * <a href="http://www.owasp.org/index.php/HTTPOnly">here</a>.
   *
   * @param httpOnly True if the cookie is HTTP only, otherwise false.
   */
  @Fluent
  Cookie setHttpOnly(boolean httpOnly);

  
Returns:
the http only status of this cookie/**
   * @return the http only status of this cookie
   */
  boolean isHttpOnly();

  
Sets the same site of this cookie.
Params:
policy – The policy should be one of CookieSameSite.
Returns:
a reference to this, so the API can be used fluently/**
   * Sets the same site of this cookie.
   *
   * @param policy The policy should be one of {@link CookieSameSite}.
   * @return a reference to this, so the API can be used fluently
   */
  @Fluent
  Cookie setSameSite(CookieSameSite policy);

  
Returns:
the SameSite policy of this cookie/**
   * @return the SameSite policy of this cookie
   */
  @Nullable
  CookieSameSite getSameSite();

  
Encode the cookie to a string. This is what is used in the Set-Cookie header
Returns:
 the encoded cookie/**
   * Encode the cookie to a string. This is what is used in the Set-Cookie header
   *
   * @return  the encoded cookie
   */
  String encode();

}