org.simpleframework.http.parse

## Class CookieParser

- java.lang.Object
- - org.simpleframework.util.parse.Parser
  - - org.simpleframework.http.parse.CookieParser

All Implemented Interfaces:
  java.lang.Iterable<Cookie>

    public class CookieParser
    extends Parser
    implements java.lang.Iterable<Cookie>

CookieParser is used to parse the cookie header. The cookie header is one of the headers that is used by the HTTP state management mechanism. The Cookie header is the header that is sent from the client to the server in response to a Set-Cookie header. The syntax of the Cookie header as taken from RFC 2109, HTTP State Management Mechanism.

      cookie          =       "Cookie:" cookie-version
                              1*((";" | ",") cookie-value)
      cookie-value    =       NAME "=" VALUE [";" path] [";" domain]
      cookie-version  =       "$Version" "=" value
      NAME            =       attr
      VALUE           =       value
      path            =       "$Path" "=" value
      domain          =       "$Domain" "=" value

The cookie header may consist of several cookies. Each cookie can be extracted from the header by examining the it syntax of the cookie header. The syntax of the cookie header is defined in RFC 2109.

Each cookie has a `$Version` attribute followed by multiple cookies. Each contains a name and a value, followed by an optional `$Path` and `$Domain` attribute. This will parse a given cookie header and return each cookie extracted as a `Cookie` object.

Author:
  Niall Gallagher

### Field Summary

### Fields inherited from class org.simpleframework.util.parse.Parser

`buf, count, off`

### Constructor Summary

Constructors
Constructor and Description
`CookieParser()` Create a `CookieParser` that contains no cookies.
`CookieParser(java.lang.String header)` This is primarily a convineance constructor.

### Method Summary

Methods
`protected void` `init()` Resets the cookie and the buffer variables for this `CookieParser`.
`java.util.Iterator<Cookie>` `iterator()` This is used to acquire the cookie values from the provided the provided source text.
`protected void` `parse()` This will extract the next `Cookie` from the buffer.
`void` `reset()` This is used so that the collection of `Cookies` can be reiterated.
`protected boolean` `skip(java.lang.String text)` This is used to skip an arbitrary `String` within the `char` buf.

### Methods inherited from class org.simpleframework.util.parse.Parser

`digit, ensureCapacity, parse, space, toLower`

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

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

### Constructor Detail

#### CookieParser

    public CookieParser()

Create a `CookieParser` that contains no cookies. the instance will return `false` for the `hasNext` method. cookies may be parsed using this instance by using the `parse` method.

#### CookieParser

    public CookieParser(java.lang.String header)

This is primarily a convineance constructor. This will parse the `String` given to extract the cookies. This could be achived by calling the default no-arg constructor and then using the instance to invoke the `parse` method on that `String`.

Parameters:
  `header` - a `String` containing a cookie value

### Method Detail

#### init

    protected void init()

Resets the cookie and the buffer variables for this `CookieParser`. It is used to set the state of the parser to start parsing a new cookie.

Specified by:
  `init` in class `Parser`

#### parse

    protected void parse()

This will extract the next `Cookie` from the buffer. If all the characters in the buffer have already been examined then this method will simply do nothing. Otherwise this will parse the remainder of the buffer and (if it follows RFC 2109) produce a `Cookie`.

Specified by:
  `parse` in class `Parser`

#### skip

    protected boolean skip(java.lang.String text)

This is used to skip an arbitrary `String` within the `char` buf. It checks the length of the `String` first to ensure that it will not go out of bounds. A comparison is then made with the buffers contents and the `String` if the reigon in the buffer matched the `String` then the offset within the buffer is increased by the `String`'s length so that it has effectively skipped it.

This `skip` method will ignore all of the whitespace text. This will also skip trailing spaces within the the input text and all spaces within the source text. For example if the input was the string "s omete xt" and the source was "some text to skip" then the result of a skip ignoring spaces would be "to skip" in the source string, as the trailing spaces are also eaten by this.

Overrides:
  `skip` in class `Parser`
Parameters:
  `text` - this is the `String` value to be skipped
Returns:
  true if the `String` was skipped

#### iterator

    public java.util.Iterator<Cookie> iterator()

This is used to acquire the cookie values from the provided the provided source text. This allows the cookie parser to be used within a for each loop to parse out the values of a cookie one by one so that they may be used or stored.

Specified by:
  `iterator` in interface `java.lang.Iterable<Cookie>`
Returns:
  this returns an iterator for extracting cookie value

#### reset

    public void reset()

This is used so that the collection of `Cookies` can be reiterated. This allows the collection to be reused. The `reset` method will invoke the super classes `init` method. This will reinitialize this `Parser` so the cookie will be reparsed.