/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you 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.milton.http;
/**
*
* @author brad
*/
public interface Cookie {
/**
* This returns the version for this cookie. The version is
* not optional and so will always return the version this
* cookie uses. If no version number is specified this will
* return a version of 1, to comply with RFC 2109.
*
* @return the version value from this cookie instance
*/
int getVersion();
/**
* This enables the version of the <code>Cookie</code> to be
* set. By default the version of the <code>Cookie</code> is
* set to 1. It is not advisable to set the version higher
* than 1, unless it is known that the client will accept it.
* <p>
* Some old browsers can only handle cookie version 0. This
* can be used to comply with the original Netscape cookie
* specification. Version 1 complies with RFC 2109.
*
* @param version this is the version number for the cookie
*/
void setVersion(int version);
/**
* This returns the name for this cookie. The name and value
* attributes of a cookie define what the <code>Cookie</code>
* is for, these values will always be present. These are
* mandatory for both the Cookie and Set-Cookie headers.
* <p>
* Because the cookie may be stored by name, the cookie name
* cannot be modified after the creation of the cookie object.
*
* @return the name from this cookie instance object
*/
String getName();
/**
* This returns the value for this cookie. The name and value
* attributes of a cookie define what the <code>Cookie</code>
* is for, these values will always be present. These are
* mandatory for both the Cookie and Set-Cookie headers.
*
* @return the value from this cookie instance object
*/
String getValue();
/**
* This enables the value of the cookie to be changed. This
* can be set to any value the server wishes to send. Cookie
* values can contain space characters as they are transmitted
* in quotes. For example a value of <code>some value</code>
* is perfectly legal. However for maximum compatibility
* across the different plaforms such as PHP, JavaScript and
* others, quotations should be avoided. If quotations are
* required they must be added to the string. For example a
* quoted value could be created as <code>"some value"</code>.
*
* @param value this is the new value of this cookie object
*/
void setValue(String value);
/**
* This determines whether the cookie is secure. The cookie
* is secure if it has the "secure" token set, as defined
* by RFC 2109. If this token is set then the cookie is only
* sent over secure channels such as SSL and TLS and ensures
* that a third party cannot intercept and spoof the cookie.
*
* @return this returns true if the "secure" token is set
*/
boolean getSecure();
/**
* This is used to determine if the client browser should send
* this cookie over a secure protocol. If this is true then
* the client browser should only send the cookie over secure
* channels such as SSL and TLS. This ensures that the value
* of the cookie cannot be intercepted by a third party.
*
* @param secure if true then the cookie should be protected
*/
void setSecure(boolean secure);
/**
* This returns the number of seconds a cookie lives for. This
* determines how long the cookie will live on the client side.
* If the expiry is less than zero the cookie lifetime is the
* duration of the client browser session, if it is zero then
* the cookie will be deleted from the client browser.
*
* @return returns the duration in seconds the cookie lives
*/
int getExpiry();
/**
* This allows a lifetime to be specified for the cookie. This
* will make use of the "max-age" token specified by RFC 2109
* the specifies the number of seconds a browser should keep
* a cookie for. This is useful if the cookie is to be kept
* beyond the lifetime of the client session. If the valie of
* this is zero then this will remove the client cookie, if
* it is less than zero then the "max-age" field is ignored.
*
* @param expiry the duration in seconds the cookie lives
*/
void setExpiry(int expiry);
/**
* This returns the path for this cookie. The path is in both
* the Cookie and Set-Cookie headers and so may return null
* if there is no domain value. If the <code>toString</code>
* or <code>toClientString</code> is invoked the path will
* not be present if the path attribute is null.
*
* @return this returns the path value from this cookie
*/
String getPath();
/**
* This is used to set the cookie path for this cookie. This
* is set so that the cookie can specify the directories that
* the cookie is sent with. For example if the path attribute
* is set to <code>/pub/bin</code>, then requests for the
* resource <code>http://hostname:port/pub/bin/README</code>
* will be issued with this cookie. The cookie is issued for
* all resources in the path and all subdirectories.
*
* @param path this is the path value for this cookie object
*/
void setPath(String path);
/**
* This returns the domain for this cookie. The domain is in
* both the Cookie and Set-Cookie headers and so may return
* null if there is no domain value. If either the
* <code>toString</code> or <code>toClientString</code> is
* invoked the domain will not be present if this is null.
*
* @return this returns the domain value from this cookie
*/
String getDomain();
/**
* This enables the domain for this <code>Cookie</code> to be
* set. The form of the domain is specified by RFC 2109. The
* value can begin with a dot, like <code>.host.com</code>.
* This means that the cookie is visible within a specific
* DNS zone like <code>www.host.com</code>. By default this
* value is null which means it is sent back to its origin.
*
* @param domain this is the domain value for this cookie
*/
void setDomain(String domain);
boolean isHttpOnly();
void setHttpOnly(boolean b);
}