org.apache.velocity.tools.view

## Class CookieTool

- java.lang.Object
- - org.apache.velocity.tools.generic.SafeConfig
  - - org.apache.velocity.tools.view.CookieTool

    @DefaultKey(value="cookies")
     @ValidScope(value="request")
    public class CookieTool
    extends SafeConfig

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$
Author:
  Dmitri Colebatch, Nathan Bubna

### Nested Class Summary

Nested Classes
`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

Fields
`protected static org.slf4j.Logger` `log`
`protected javax.servlet.http.HttpServletRequest` `request`
`protected javax.servlet.http.HttpServletResponse` `response`

### Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

`LOCK_CONFIG_KEY, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY`

### Constructor Summary

Constructors
Constructor and Description
`CookieTool()`

### Method Summary

All Methods Instance Methods Concrete Methods
`String` `add(javax.servlet.http.Cookie c)` Adds the specified Cookie to the HttpServletResponse.
`String` `add(String name, String value)` Adds a new Cookie with the specified name and value to the HttpServletResponse.
`String` `add(String name, String value, Object maxAge)` Convenience method to add a new Cookie to the response and set an expiry time for it.
`javax.servlet.http.Cookie` `create(String name, String value)` Creates a new Cookie with the specified name and value.
`javax.servlet.http.Cookie` `create(String name, String value, Object maxAge)` Convenience method to create a new Cookie and set an expiry time for it.
`String` `delete(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(String name)` Returns the Cookie with the specified name, if it exists.
`List<javax.servlet.http.Cookie>` `getAll()` Expose array of Cookies for this request to the template.
`void` `setRequest(javax.servlet.http.HttpServletRequest request)` Sets the current `HttpServletRequest`.
`void` `setResponse(javax.servlet.http.HttpServletResponse response)` Sets the current `HttpServletResponse`.
`String` `toString()`

### Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

`configure, configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode`

### Methods inherited from class java.lang.Object

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

### Field Detail

#### log

    protected static org.slf4j.Logger log

#### request

    protected javax.servlet.http.HttpServletRequest request

#### response

    protected javax.servlet.http.HttpServletResponse response

### 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`.

Parameters:
  `request` - servlet request

#### 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`.

Parameters:
  `response` - servlet response

#### getAll

    public 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(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`

Parameters:
  `name` - cookie name
Returns:
  found cookie or null

#### add

    public 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 String add(String name,
                      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 String add(String name,
                      String value,
                      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(String name,
                                            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(String name,
                                            String value,
                                            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 String delete(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 String toString()

Overrides:
  `toString` in class `Object`