package com.bradmcevoy.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); }