org.apache.http.message

## Class BasicHeaderValueFormatter

- java.lang.Object
- - org.apache.http.message.BasicHeaderValueFormatter

- All Implemented Interfaces:
    HeaderValueFormatter

      @Immutable
      public class BasicHeaderValueFormatter
      extends Object
      implements HeaderValueFormatter

  Basic implementation for formatting header value elements. Instances of this class are stateless and thread-safe. Derived classes are expected to maintain these properties.
  Since:
    4.0

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static BasicHeaderValueFormatter` | `DEFAULT` Deprecated. (4.3) use `INSTANCE`
    `static BasicHeaderValueFormatter` | `INSTANCE`
    `static String` | `SEPARATORS` Special characters that can be used as separators in HTTP parameters.
    `static String` | `UNSAFE_CHARS` Unsafe special characters that must be escaped using the backslash character

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BasicHeaderValueFormatter()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `doFormatValue(CharArrayBuffer buffer, String value, boolean quote)` Actually formats the value of a name-value pair.
    `protected int` | `estimateElementsLen(HeaderElement[] elems)` Estimates the length of formatted header elements.
    `protected int` | `estimateHeaderElementLen(HeaderElement elem)` Estimates the length of a formatted header element.
    `protected int` | `estimateNameValuePairLen(NameValuePair nvp)` Estimates the length of a formatted name-value pair.
    `protected int` | `estimateParametersLen(NameValuePair[] nvps)` Estimates the length of formatted parameters.
    `CharArrayBuffer` | `formatElements(CharArrayBuffer charBuffer, HeaderElement[] elems, boolean quote)` Formats an array of header elements.
    `static String` | `formatElements(HeaderElement[] elems, boolean quote, HeaderValueFormatter formatter)` Formats an array of header elements.
    `CharArrayBuffer` | `formatHeaderElement(CharArrayBuffer charBuffer, HeaderElement elem, boolean quote)` Formats one header element.
    `static String` | `formatHeaderElement(HeaderElement elem, boolean quote, HeaderValueFormatter formatter)` Formats a header element.
    `CharArrayBuffer` | `formatNameValuePair(CharArrayBuffer charBuffer, NameValuePair nvp, boolean quote)` Formats one name-value pair, where the value is optional.
    `static String` | `formatNameValuePair(NameValuePair nvp, boolean quote, HeaderValueFormatter formatter)` Formats a name-value pair.
    `CharArrayBuffer` | `formatParameters(CharArrayBuffer charBuffer, NameValuePair[] nvps, boolean quote)` Formats the parameters of a header element.
    `static String` | `formatParameters(NameValuePair[] nvps, boolean quote, HeaderValueFormatter formatter)` Formats a set of parameters.
    `protected boolean` | `isSeparator(char ch)` Checks whether a character is a `separator`.
    `protected boolean` | `isUnsafe(char ch)` Checks whether a character is `unsafe`.

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

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

- - ### Field Detail

    - #### DEFAULT

          @Deprecated
          public static final BasicHeaderValueFormatter DEFAULT

      Deprecated. (4.3) use `INSTANCE`
      A default instance of this class, for use as default or fallback. Note that `BasicHeaderValueFormatter` is not a singleton, there can be many instances of the class itself and of derived classes. The instance here provides non-customized, default behavior.

    - #### INSTANCE

          public static final BasicHeaderValueFormatter INSTANCE

    - #### SEPARATORS

          public static final String SEPARATORS

      Special characters that can be used as separators in HTTP parameters. These special characters MUST be in a quoted string to be used within a parameter value .
      See Also:
        Constant Field Values

    - #### UNSAFE_CHARS

          public static final String UNSAFE_CHARS

      Unsafe special characters that must be escaped using the backslash character
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### BasicHeaderValueFormatter

          public BasicHeaderValueFormatter()

  - ### Method Detail

    - #### formatElements

          public static String formatElements(HeaderElement[] elems,
                              boolean quote,
                              HeaderValueFormatter formatter)

      Formats an array of header elements.
      Parameters:
        `elems` - the header elements to format
        `quote` - `true` to always format with quoted values, `false` to use quotes only when necessary
        `formatter` - the formatter to use, or `null` for the `default`
      Returns:
        the formatted header elements

    - #### formatElements

          public CharArrayBuffer formatElements(CharArrayBuffer charBuffer,
                                       HeaderElement[] elems,
                                       boolean quote)

      Description copied from interface: `HeaderValueFormatter`
      Formats an array of header elements.
      Specified by:
        `formatElements` in interface `HeaderValueFormatter`
      Parameters:
        `charBuffer` - the buffer to append to, or `null` to create a new buffer
        `elems` - the header elements to format
        `quote` - `true` to always format with quoted values, `false` to use quotes only when necessary
      Returns:
        a buffer with the formatted header elements. If the `buffer` argument was not `null`, that buffer will be used and returned.

    - #### estimateElementsLen

          protected int estimateElementsLen(HeaderElement[] elems)

      Estimates the length of formatted header elements.
      Parameters:
        `elems` - the header elements to format, or `null`
      Returns:
        a length estimate, in number of characters

    - #### formatHeaderElement

          public static String formatHeaderElement(HeaderElement elem,
                                   boolean quote,
                                   HeaderValueFormatter formatter)

      Formats a header element.
      Parameters:
        `elem` - the header element to format
        `quote` - `true` to always format with quoted values, `false` to use quotes only when necessary
        `formatter` - the formatter to use, or `null` for the `default`
      Returns:
        the formatted header element

    - #### formatHeaderElement

          public CharArrayBuffer formatHeaderElement(CharArrayBuffer charBuffer,
                                            HeaderElement elem,
                                            boolean quote)

      Description copied from interface: `HeaderValueFormatter`
      Formats one header element.
      Specified by:
        `formatHeaderElement` in interface `HeaderValueFormatter`
      Parameters:
        `charBuffer` - the buffer to append to, or `null` to create a new buffer
        `elem` - the header element to format
        `quote` - `true` to always format with quoted values, `false` to use quotes only when necessary
      Returns:
        a buffer with the formatted header element. If the `buffer` argument was not `null`, that buffer will be used and returned.

    - #### estimateHeaderElementLen

          protected int estimateHeaderElementLen(HeaderElement elem)

      Estimates the length of a formatted header element.
      Parameters:
        `elem` - the header element to format, or `null`
      Returns:
        a length estimate, in number of characters

    - #### formatParameters

          public static String formatParameters(NameValuePair[] nvps,
                                boolean quote,
                                HeaderValueFormatter formatter)

      Formats a set of parameters.
      Parameters:
        `nvps` - the parameters to format
        `quote` - `true` to always format with quoted values, `false` to use quotes only when necessary
        `formatter` - the formatter to use, or `null` for the `default`
      Returns:
        the formatted parameters

    - #### formatParameters

          public CharArrayBuffer formatParameters(CharArrayBuffer charBuffer,
                                         NameValuePair[] nvps,
                                         boolean quote)

      Description copied from interface: `HeaderValueFormatter`
      Formats the parameters of a header element. That's a list of name-value pairs, to be separated by semicolons. This method will not generate a leading semicolon.
      Specified by:
        `formatParameters` in interface `HeaderValueFormatter`
      Parameters:
        `charBuffer` - the buffer to append to, or `null` to create a new buffer
        `nvps` - the parameters (name-value pairs) to format
        `quote` - `true` to always format with quoted values, `false` to use quotes only when necessary
      Returns:
        a buffer with the formatted parameters. If the `buffer` argument was not `null`, that buffer will be used and returned.

    - #### estimateParametersLen

          protected int estimateParametersLen(NameValuePair[] nvps)

      Estimates the length of formatted parameters.
      Parameters:
        `nvps` - the parameters to format, or `null`
      Returns:
        a length estimate, in number of characters

    - #### formatNameValuePair

          public static String formatNameValuePair(NameValuePair nvp,
                                   boolean quote,
                                   HeaderValueFormatter formatter)

      Formats a name-value pair.
      Parameters:
        `nvp` - the name-value pair to format
        `quote` - `true` to always format with a quoted value, `false` to use quotes only when necessary
        `formatter` - the formatter to use, or `null` for the `default`
      Returns:
        the formatted name-value pair

    - #### formatNameValuePair

          public CharArrayBuffer formatNameValuePair(CharArrayBuffer charBuffer,
                                            NameValuePair nvp,
                                            boolean quote)

      Description copied from interface: `HeaderValueFormatter`
      Formats one name-value pair, where the value is optional.
      Specified by:
        `formatNameValuePair` in interface `HeaderValueFormatter`
      Parameters:
        `charBuffer` - the buffer to append to, or `null` to create a new buffer
        `nvp` - the name-value pair to format
        `quote` - `true` to always format with a quoted value, `false` to use quotes only when necessary
      Returns:
        a buffer with the formatted name-value pair. If the `buffer` argument was not `null`, that buffer will be used and returned.

    - #### estimateNameValuePairLen

          protected int estimateNameValuePairLen(NameValuePair nvp)

      Estimates the length of a formatted name-value pair.
      Parameters:
        `nvp` - the name-value pair to format, or `null`
      Returns:
        a length estimate, in number of characters

    - #### doFormatValue

          protected void doFormatValue(CharArrayBuffer buffer,
                           String value,
                           boolean quote)

      Actually formats the value of a name-value pair. This does not include a leading = character. Called from `formatNameValuePair`.
      Parameters:
        `buffer` - the buffer to append to, never `null`
        `value` - the value to append, never `null`
        `quote` - `true` to always format with quotes, `false` to use quotes only when necessary

    - #### isSeparator

          protected boolean isSeparator(char ch)

      Checks whether a character is a `separator`.
      Parameters:
        `ch` - the character to check
      Returns:
        `true` if the character is a separator, `false` otherwise

    - #### isUnsafe

          protected boolean isUnsafe(char ch)

      Checks whether a character is `unsafe`.
      Parameters:
        `ch` - the character to check
      Returns:
        `true` if the character is unsafe, `false` otherwise

Copyright © 2005–2013 The Apache Software Foundation. All rights reserved.