org.simpleframework.http.parse

## Class ListParser<T>

- java.lang.Object
- - org.simpleframework.util.parse.Parser
  - - org.simpleframework.http.parse.ListParser<T>

Direct Known Subclasses:
  LanguageParser, ValueParser

    public abstract class ListParser<T>
    extends Parser

The `ListParser` is used to extract a comma separated list of HTTP header values. This will extract values without any leading or trailing spaces, which enables the values to be used. Listing the values that appear in the header also requires that the values are ordered. This orders the values using the values that appear with any quality parameter associated with it. The quality value is a special parameter that often found in a comma separated value list to specify the client preference.

        image/gif, image/jpeg, text/html
        image/gif;q=1.0, image/jpeg;q=0.8, image/png;  q=1.0,*;q=0.1
        gzip;q=1.0, identity; q=0.5, *;q=0

The above lists taken from RFC 2616 provides an example of the common form comma separated values take. The first illustrates a simple comma delimited list, here the ordering of values is determined from left to right. The second and third list have quality values associated with them, these are used to specify a preference and thus order.

Each value within a list has an implicit quality value of 1.0. If the value is explicitly set with a the "q" parameter, then the values can range from 1.0 to 0.001. This parser ensures that the order of values returned from the `list` method adheres to the optional quality parameters and ensures that the quality parameters a removed from the resulting text.

Author:
  Niall Gallagher

### Field Summary

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

`buf, count, off`

### Constructor Summary

Constructors
Constructor and Description
`ListParser()` Constructor for the `ListParser`.
`ListParser(java.util.List<java.lang.String> list)` Constructor for the `ListParser`.
`ListParser(java.lang.String text)` Constructor for the `ListParser`.

### Method Summary

Methods
`protected abstract T` `create(char[] text, int start, int len)` This creates an value object using the range of characters that have been parsed as an item within the list of values.
`protected void` `init()` Initializes the parser so that tokens can be extracted from the list.
`java.util.List<T>` `list()` This will build an ordered list of values extracted from the comma separated header value.
`protected void` `parse()` This ensures that tokens are taken from the comma separated list as long as there bytes left to be examined within the source text.
`void` `parse(java.util.List<java.lang.String> list)` This allows multiple header values to be represented as one single comma separated list.

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

`digit, ensureCapacity, parse, skip, space, toLower`

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

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

### Constructor Detail

#### ListParser

    public ListParser()

Constructor for the `ListParser`. This creates a parser with no initial parse data, if there are headers to be parsed then the `parse(String)` method or `parse(List)` method can be used. This will parse a delimited list according so RFC 2616 section 4.2.

#### ListParser

    public ListParser(java.lang.String text)

Constructor for the `ListParser`. This creates a parser with the text supplied. This will parse the comma separated list according to RFC 2616 section 2.1 and 4.2. The tokens can be extracted using the `list` method, which will also sort and trim the tokens.

Parameters:
  `text` - this is the comma separated list to be parsed

#### ListParser

    public ListParser(java.util.List<java.lang.String> list)

Constructor for the `ListParser`. This creates a parser with the text supplied. This will parse the comma separated list according to RFC 2616 section 2.1 and 4.2. The tokens can be extracted using the `list` method, which will also sort and trim the tokens.

Parameters:
  `list` - a list of comma separated lists to be parsed

### Method Detail

#### parse

    public void parse(java.util.List<java.lang.String> list)

This allows multiple header values to be represented as one single comma separated list. RFC 2616 states that multiple message header fields with the same field name may be present in a message if and only if the entire field value for that header field is defined as a comma separated list. This means that if there are multiple header values with the same name they can be combined into a single comma separated list.

Parameters:
  `list` - this is a list of header values to be combined

#### list

    public java.util.List<T> list()

This will build an ordered list of values extracted from the comma separated header value. This enables the most preferred token, to be taken from the first index of the array and the least preferred token to be taken from the last index.

Returns:
  tokens parsed from the list ordered by preference

#### parse

    protected void parse()

This ensures that tokens are taken from the comma separated list as long as there bytes left to be examined within the source text. This also makes sure that the implicit qvalue is decreased each time a token is extracted from the list.

Specified by:
  `parse` in class `Parser`

#### init

    protected void init()

Initializes the parser so that tokens can be extracted from the list. This creates a write buffer so that a if there is only one token as long as the source text, then that token can be accommodated, also this starts of the initial qvalue implicit to tokens within the list as the maximum long value.

One thing that should be noted is that this will not empty the priority queue on each string parsed. This ensures that if there are multiple strings they can be parsed quickly and also contribute to the final result.

Specified by:
  `init` in class `Parser`

#### create

    protected abstract T create(char[] text,
           int start,
           int len)

This creates an value object using the range of characters that have been parsed as an item within the list of values. It is up to the implementation to create a value to insert in to the list. A null value will be ignored if returned.

Parameters:
  `text` - this is the text buffer to acquire the value from
  `start` - the offset within the array to take characters
  `len` - this is the number of characters within the token