Package org.apache.tapestry5.services

## Interface Cookies

- All Known Implementing Classes:
    `CookiesImpl`

      public interface Cookies

  Used by other services to obtain cookie values for the current request, or to write cookie values as part of the request. Note that when writing cookies, the cookie's secure flag will match `Request.isSecure()`.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `CookieBuilder` | `getBuilder​(String name, String value)` | Returns a `CookieBuilder` to build and write a `Cookie`.
    `String` | `readCookieValue​(String name)` | Returns the value of the first cookie whose name matches.
    `void` | `removeCookieValue​(String name)` | Removes a previously written cookie, by writing a new cookie with a maxAge of 0.
    `void` | `writeCookieValue​(String name, String value)` | Deprecated. Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.
    `void` | `writeCookieValue​(String name, String value, int maxAge)` | Deprecated. Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.
    `void` | `writeCookieValue​(String name, String value, String path)` | Deprecated. Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.
    `void` | `writeCookieValue​(String name, String value, String path, String domain)` | Deprecated. Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.
    `void` | `writeDomainCookieValue​(String name, String value, String domain)` | Deprecated. Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.
    `void` | `writeDomainCookieValue​(String name, String value, String domain, int maxAge)` | Deprecated. Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.

- - ### Method Detail

    - #### readCookieValue

          String readCookieValue​(String name)

      Returns the value of the first cookie whose name matches. Returns null if no such cookie exists. This method is only aware of cookies that are part of the incoming request; it does not know about additional cookies added since then (via `writeCookieValue(String, String)`).

    - #### writeCookieValue

          void writeCookieValue​(String name,
                                String value)

      Deprecated.
      Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.
      Creates or updates a cookie value. The value is stored using a max age (in seconds) defined by the symbol `org.apache.tapestry5.default-cookie-max-age`. The factory default for this value is the equivalent of one week.

    - #### writeCookieValue

          void writeCookieValue​(String name,
                                String value,
                                int maxAge)

      Deprecated.
      Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.
      As with `writeCookieValue(String, String)` but an explicit maximum age may be set.
      Parameters:
        `name` - the name of the cookie
        `value` - the value to be stored in the cookie
        `maxAge` - the maximum age, in seconds, to store the cookie

    - #### writeCookieValue

          void writeCookieValue​(String name,
                                String value,
                                String path)

      Deprecated.
      Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.
      As with `writeCookieValue(String, String)` but an explicit path may be set.

    - #### writeDomainCookieValue

          void writeDomainCookieValue​(String name,
                                      String value,
                                      String domain)

      Deprecated.
      Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.
      As with `writeCookieValue(String, String)` but an explicit domain may be set.

    - #### writeDomainCookieValue

          void writeDomainCookieValue​(String name,
                                      String value,
                                      String domain,
                                      int maxAge)

      Deprecated.
      Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.
      As with `writeCookieValue(String, String)` but an explicit domain and maximum age may be set.

    - #### writeCookieValue

          void writeCookieValue​(String name,
                                String value,
                                String path,
                                String domain)

      Deprecated.
      Use the `CookieBuilder` API, obtained with `getBuilder(String, String)`, instead.
      As with `writeCookieValue(String, String, String)` but an explicit domain and path may be set.

    - #### removeCookieValue

          void removeCookieValue​(String name)

      Removes a previously written cookie, by writing a new cookie with a maxAge of 0. Only deletes a cookie with the default path and no domain set. For deleting other cookies use `CookieBuilder.delete()`. An instance of the `CookieBuilder` API can be obtained with `getBuilder(String, String)`.

    - #### getBuilder

          CookieBuilder getBuilder​(String name,
                                   String value)

      Returns a `CookieBuilder` to build and write a `Cookie`. The default implementation creates a cookie who's value is stored using a max age (in seconds) defined by the symbol `org.apache.tapestry5.default-cookie-max-age`. The factory default for this value is the equivalent of one week. The default path is the context path (see `Request.getContextPath()`) of the current Request, the default secure setting is to send the cookie over secure channels only, if the original request was secure (see `Request.isSecure()`
      Parameters:
        `name` - the name of the cookie
        `value` - the value of the cookie
      Returns:
        a `CookieBuilder` for setting additional cookie attributes and writing it out
      Since:
        5.4