org.apache.velocity.tools.view
Class CookieTool

java.lang.Object
  org.apache.velocity.tools.view.CookieTool

Direct Known Subclasses:

CookieTool

@DefaultKey(value="cookies")
@ValidScope(value="request")
public class CookieTool
extends java.lang.Object

View tool for convenient cookie access and creation.

 Template example(s):
  $cookie.foo
  $cookie.add("bar",'woogie')

 tools.xml configuration:
 <tools>
   <toolbox scope="request">
     <tool class="org.apache.velocity.tools.view.CookieTool"/>
   </toolbox>
 </tools>
 

This class is only designed for use as a request-scope tool.

Since:

VelocityTools 2.0

Version:

$Id: CookieTool.java 740389 2009-02-03 19:38:36Z nbubna $

Author:

Dmitri Colebatch, Nathan Bubna

Nested Class Summary

static class

CookieTool.SugarCookie Extends Cookie to add some fluid API sugar and a toString() method that renders the Cookie's value instead of the usual Object.toString() shenanigans.

Field Summary

private java.util.List<javax.servlet.http.Cookie>	jar
protected org.apache.velocity.runtime.log.Log	log
protected javax.servlet.http.HttpServletRequest	request
protected javax.servlet.http.HttpServletResponse	response

Constructor Summary

CookieTool()

Method Summary

java.lang.String	add(javax.servlet.http.Cookie c) Adds the specified Cookie to the HttpServletResponse.
java.lang.String	add(java.lang.String name, java.lang.String value) Adds a new Cookie with the specified name and value to the HttpServletResponse.
java.lang.String	add(java.lang.String name, java.lang.String value, java.lang.Object maxAge) Convenience method to add a new Cookie to the response and set an expiry time for it.
javax.servlet.http.Cookie	create(java.lang.String name, java.lang.String value) Creates a new Cookie with the specified name and value.
javax.servlet.http.Cookie	create(java.lang.String name, java.lang.String value, java.lang.Object maxAge) Convenience method to create a new Cookie and set an expiry time for it.
java.lang.String	delete(java.lang.String name) Retrieves the specified cookie and sets the Max-Age to 0 to tell the browser to delete the cookie.
javax.servlet.http.Cookie	get(java.lang.String name) Returns the Cookie with the specified name, if it exists.
java.util.List<javax.servlet.http.Cookie>	getAll() Expose array of Cookies for this request to the template.
void	setLog(org.apache.velocity.runtime.log.Log log) Sets the Log used for logging messages when Cookie creation fails due to an invalid name.
void	setRequest(javax.servlet.http.HttpServletRequest request) Sets the current HttpServletRequest.
void	setResponse(javax.servlet.http.HttpServletResponse response) Sets the current HttpServletResponse.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

request

protected javax.servlet.http.HttpServletRequest request

response

protected javax.servlet.http.HttpServletResponse response

log

protected org.apache.velocity.runtime.log.Log log

jar

private java.util.List<javax.servlet.http.Cookie> jar

Constructor Detail

CookieTool

public CookieTool()

Method Detail

setRequest

public void setRequest(javax.servlet.http.HttpServletRequest request)

Sets the current HttpServletRequest. This is required for this tool to operate and will throw a NullPointerException if this is not set or is set to null.

setResponse

public void setResponse(javax.servlet.http.HttpServletResponse response)

Sets the current HttpServletResponse. This is required for this tool to operate and will throw a NullPointerException if this is not set or is set to null.

setLog

public void setLog(org.apache.velocity.runtime.log.Log log)

Sets the Log used for logging messages when Cookie creation fails due to an invalid name.

getAll

public java.util.List<javax.servlet.http.Cookie> getAll()

Expose array of Cookies for this request to the template.

This is equivalent to $request.cookies.

Returns:

list of Cookie objects for this request

get

public javax.servlet.http.Cookie get(java.lang.String name)

Returns the Cookie with the specified name, if it exists.

So, if you had a cookie named 'foo', you'd get it's value by $cookies.foo.value or it's max age by $cookies.foo.maxAge

add

public java.lang.String add(javax.servlet.http.Cookie c)

Adds the specified Cookie to the HttpServletResponse. This does *not* add the Cookie to the current request.

Parameters:

c - is for cookie (that's good enough for me)

Returns:

an empty String to prevent the reference from rendering unless the cookie passed in is null, then it returns null

Since:

VelocityTools 2.0

add

public java.lang.String add(java.lang.String name,
                            java.lang.String value)

Adds a new Cookie with the specified name and value to the HttpServletResponse. This does *not* add a Cookie to the current request.

Parameters:

name - the name to give this cookie

value - the value to be set for this cookie

Returns:

an empty String to prevent the reference from rendering

add

public java.lang.String add(java.lang.String name,
                            java.lang.String value,
                            java.lang.Object maxAge)

Convenience method to add a new Cookie to the response and set an expiry time for it.

Parameters:

name - the name to give this cookie

value - the value to be set for this cookie

maxAge - the expiry to be set for this cookie

Returns:

an empty String to prevent the reference from rendering

create

public javax.servlet.http.Cookie create(java.lang.String name,
                                        java.lang.String value)

Creates a new Cookie with the specified name and value. This does *not* add the Cookie to the response, so the created Cookie will not be set unless you do $cookies.add($myCookie).

Parameters:

name - the name to give this cookie

value - the value to be set for this cookie

Returns:

The new SugarCookie object.

Since:

VelocityTools 1.3

create

public javax.servlet.http.Cookie create(java.lang.String name,
                                        java.lang.String value,
                                        java.lang.Object maxAge)

Convenience method to create a new Cookie and set an expiry time for it.

Parameters:

name - the name to give this cookie

value - the value to be set for this cookie

maxAge - the expiry to be set for this cookie

Returns:

The new SugarCookie object.

Since:

VelocityTools 1.3

delete

public java.lang.String delete(java.lang.String name)

Retrieves the specified cookie and sets the Max-Age to 0 to tell the browser to delete the cookie. Then this returns an empty string to make this render silently. If no such cookie exists, then it returns null to show the error.

Parameters:

name - the name of the cookie to be eaten

Returns:

empty string, or null if no such cookie exists

See Also:

Cookie.setMaxAge(int), add(Cookie), get(String)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object