Cookie.java

/***************************************************************************
   Copyright 2008 Emily Estes

   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 net.metanotion.web;


/** This is an abstract interface representing a Cookie. */
public interface Cookie {
	/** This is just a handy constant to use for cookies that should last "forever".
		Basically it's approximately one year in seconds.
	*/
	public static final int ONE_YEAR_IN_SECONDS = 60*60*24*365;
	/** This enum is used to state whether this cookie should be transmitted over secure connections only or not. */
	public enum Security {
		/** The cookie should ONLY be transmitted over an SSL secured session. */ SSL,
		/** The cookie can be transmitted over a plain-text connection. */ NONE };
	/** This enum is used to state whether a cookie should be marked for HTTP only access, or if JavaScript on the
		client can access it. */
	public enum Access {
		/** The cookie may only be sent back to the server and is not to be accessible to JavaScript. */ HTTP,
		/** The client can expose the cookie to client-side scripting languages. */ ALL };
	/** The cookie specification this cookie complies with. */
	public enum Version {
		/** This cookie complies with the original Netscape cookie spec. */ NETSCAPE,
		/** This cookie complies with RFC 2109. */ RFC2109 }

	/** Retrieve the comment associated with this cookie.
		@return The string representing the comment. */
	public String getComment();
	/** Retrieve the domain associated with this cookie.
		@return the Domain name this cookie is attached to. */
	public String getDomain();
	/** Retrieve the maximum amount of time the client should store this cookie.
		@return The maximum amount of time in seconds that the client should
			cache this cookie. */
	public int getMaxAge();
	/** Retrieve the name of this cookie.
		@return The name of the cookie.
	*/
	public String getName();
	/** Retrieve the resource path this cookie is associated with.
		@return The path associated with the cookie.
	*/
	public String getPath();
	/** Retrieve whether this coooke is allowed to be sent over unencrypted connections.
		@return Security.SSL if this cookie is ONLY to be sent over HTTPS connections. Security.NONE otherwise.
	*/
	public Security getSecure();
	/** Retrieve whether this cookie is allowed to be access from JavaScript or not on the client.
		@return Access.HTTP if JS is NOT allowed to access this cookie, Access.ALL otherwise.
	*/
	public Access getHttpOnly();
	/** Retrieve the value stored in this cookie.
		@return The value of the cookie.
	*/
	public String getValue();
	/** Return the version of this cookie.
		@return Which spec this cookie complies with.
	*/
	public Version getVersion();
}