Class 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.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private class  CookieParser.Sequence
      This is used to represent an Iterator that will iterate over the available cookies within the provided source text.
      private class  CookieParser.Token
      This is a token object that is used to store the offset and length of a region of chars in the CookieParser.buf array.
    • Constructor Summary

      Constructors 
      Constructor Description
      CookieParser()
      Create a CookieParser that contains no cookies.
      CookieParser​(java.lang.String header)
      This is primarily a convineance constructor.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private void cookie()
      This is used to parse a Cookie from the buffer that contains the Cookie values.
      private void data()
      This initializes the value token and extracts the value of this Cookie.
      private void domain()
      Initializes the domain token and extracts the $Domain of this Cookie.
      private Cookie getCookie()
      Creates the Cookie from the token objects.
      private Cookie getCookie​(java.lang.String name, java.lang.String value)
      Creates the Cookie from the token objects.
      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.
      private void name()
      This initializes the name token and extracts the name of this Cookie.
      protected void parse()
      This will extract the next Cookie from the buffer.
      private void path()
      This initializes the path token and extracts the $Path of this Cookie.
      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.
      private boolean terminal​(char ch)
      This is used to determine if a given iso8859-1 character is a terminal character.
      private void value()
      Used to extract everything found after the NAME '=' within a Cookie.
      private void version()
      This extracts the $Version of this Cookie.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator
    • Field Detail

      • finished

        private boolean finished
        Determines when the Parser has finished.
      • parsed

        private boolean parsed
        Used so the Parser does not parse twice.
      • version

        private int version
        Version of the Cookie being parsed.
    • 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.
      • getCookie

        private Cookie getCookie()
        Creates the Cookie from the token objects. It is assumed that the Cookie String has been parsed when this is called. This should only be used after the parse method has been called.

        If there is no $Domain or $Path within the Cookie String then the getDomain and getPath are null.

        Returns:
        the Cookie that was just parsed
      • getCookie

        private Cookie getCookie​(java.lang.String name,
                                 java.lang.String value)
        Creates the Cookie from the token objects. It is assumed that the Cookie String has been parsed when this is called. This should only be used after the parse method has been called.

        If there is no $Domain or $Path within the Cookie String then the getDomain and getPath are null.

        Parameters:
        name - the name that the Cookie contains
        value - the value that the Cookie contains
        Returns:
        the Cookie that was just parsed
      • cookie

        private void cookie()
        This is used to parse a Cookie from the buffer that contains the Cookie values. This will first try to remove any trailing value after the version/prev Cookie once this is removed it will extract the name/value pair from the Cookie. The name and value of the Cookie will be saved by the name and value tokens.
      • name

        private void name()
        This initializes the name token and extracts the name of this Cookie. The offset and length of the name will be saved in the name token. This will read all char's upto but excluding the first '=' char encountered from the off within the buffer.
      • value

        private void value()
        Used to extract everything found after the NAME '=' within a Cookie. This extracts the Cookie value the $Path and $Domain attributes if they exist (i.e. $Path and $Domain are optional in a cookie see RFC 2109).

        The path method reads the terminal found before it as does the domain method that is ";$Path" is read as the first part of the path method. This is because if there is no path the parser should not read data it does not know belongs to a specific part of the Cookie.

      • data

        private void data()
        This initializes the value token and extracts the value of this Cookie. The offset and length of the value will be saved in the value token. This will read all char's upto but excluding the first terminal char encountered from the off within the buffer, or if the value is a literal it will read a literal from the buffer (literal is any data between quotes except if the quote is prefixed with a backward slash character that is '\').
      • path

        private void path()
        This initializes the path token and extracts the $Path of this Cookie. The offset and length of the path will be saved in the path token. This will read all char's up to but excluding the first terminal char encountered from the off within the buffer, or if the value is a literal it will read a literal from the buffer (literal is any data between quotes except if the quote is prefixed with a backward slash character, that is '\').

        This reads the terminal before the $Path so that if there is no $Path for the Cookie then the character before it will not be read needlessly.

      • domain

        private void domain()
        Initializes the domain token and extracts the $Domain of this Cookie. The offset and length of the domain will be saved in the path token. This will read all characters up to but excluding the first terminal char encountered from the off within the buffer, or if the value is a literal it will read a literal from the buffer (literal is any data between quotes except if the quote is prefixed with a backward slash character, that is '\').

        This reads the terminal before the $Domain so that if there is no $Domain for the Cookie then the character before it will not be read needlessly.

      • version

        private void version()
        This extracts the $Version of this Cookie. The version is parsed and converted into a decimal int from the digit characters that make up a version.

        This will read all digit char's up to but excluding the first non digit char that it encounters from the offset within the buffer, or if the value is a literal it will read a literal from the buffer (literal is any data between quotes except if the quote is prefixed with a backward slash character i.e. '\').

      • terminal

        private boolean terminal​(char ch)
        This is used to determine if a given iso8859-1 character is a terminal character. That is either the ';' or ',' characters. Although the RFC 2109 says the terminal can be either a comma, it is not used by any browsers.
        Parameters:
        ch - the character that is to be compared
        Returns:
        true if this is a semicolon character