Package org.simpleframework.http.parse

## Class ContentParser

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

- All Implemented Interfaces:
    `ContentType`

      public class ContentParser
      extends Parser
      implements ContentType

  This provides access to the MIME type parts, that is the primary type, the secondary type and an optional character set parameter. The `charset` parameter is one of many parameters that can be associated with a MIME type. This however this exposes this parameter with a typed method.

  The `getCharset` will return the character encoding the content type is encoded within. This allows the user of the content to decode it correctly. Other parameters can be acquired from this by simply providing the name of the parameter.

  Author:
    Niall Gallagher

- - ### Field Summary

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

      `buf, count, off`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ContentParser()` | The default constructor will create a `ContentParser` that contains no charset, type or subtype.
    `ContentParser​(java.lang.String header)` | This is primarily a convenience constructor.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.String` | `getCharset()` | This is used to retrieve the `charset` of this MIME type.
    `java.lang.String` | `getParameter​(java.lang.String name)` | This is used to retrieve an arbitrary parameter from the MIME type header.
    `java.lang.String` | `getPrimary()` | This is used to retrieve the primary type of this MIME type.
    `java.lang.String` | `getSecondary()` | This is used to retrieve the secondary type of this MIME type.
    `protected void` | `init()` | This will initialize the parser when it is ready to parse a new `String`.
    `protected void` | `parse()` | Reads and parses the MIME type from the given `String` object.
    `void` | `setCharset​(java.lang.String enc)` | This will set the `charset` to whatever value the string contains.
    `void` | `setParameter​(java.lang.String name, java.lang.String value)` | This will add a named parameter to the content type header.
    `void` | `setPrimary​(java.lang.String primary)` | This sets the primary type to whatever value is in the string provided is.
    `void` | `setSecondary​(java.lang.String type)` | This sets the secondary type to whatever value is in the string provided is.
    `java.lang.String` | `toString()` | This will return the value of the MIME type as a string.

    - ### 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, wait, wait, wait`

- - ### Constructor Detail

    - #### ContentParser

          public ContentParser()

      The default constructor will create a `ContentParser` that contains no charset, type or subtype. This can be used to extract the type, subtype and the optional `charset` parameter by using the parser's `parse(String)` method.

    - #### ContentParser

          public ContentParser​(java.lang.String header)

      This is primarily a convenience constructor. This will parse the `String` given to extract the MIME type. 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` - `String` containing a MIME type value

  - ### Method Detail

    - #### setPrimary

          public void setPrimary​(java.lang.String primary)

      This sets the primary type to whatever value is in the string provided is. If the string is null then this will contain a null string for the primary type of the parameter, which is likely invalid in most cases.
      Specified by:
        `setPrimary` in interface `ContentType`
      Parameters:
        `primary` - the type to set for the primary type of this

    - #### getPrimary

          public java.lang.String getPrimary()

      This is used to retrieve the primary type of this MIME type. The primary type part within the MIME type defines the generic type. For example `text/plain; charset=UTF-8`. This will return the text value. If there is no primary type then this will return `null` otherwise the string value.
      Specified by:
        `getPrimary` in interface `ContentType`
      Returns:
        the primary type part of this MIME type

    - #### setSecondary

          public void setSecondary​(java.lang.String type)

      This sets the secondary type to whatever value is in the string provided is. If the string is null then this will contain a null string for the secondary type of the parameter, which is likely invalid in most cases.
      Specified by:
        `setSecondary` in interface `ContentType`
      Parameters:
        `type` - the type to set for the primary type of this

    - #### getSecondary

          public java.lang.String getSecondary()

      This is used to retrieve the secondary type of this MIME type. The secondary type part within the MIME type defines the generic type. For example `text/html; charset=UTF-8`. This will return the HTML value. If there is no secondary type then this will return `null` otherwise the string value.
      Specified by:
        `getSecondary` in interface `ContentType`
      Returns:
        the primary type part of this MIME type

    - #### setCharset

          public void setCharset​(java.lang.String enc)

      This will set the `charset` to whatever value the string contains. If the string is null then this will not set the parameter to any value and the `toString` method will not contain any details of the parameter.
      Specified by:
        `setCharset` in interface `ContentType`
      Parameters:
        `enc` - parameter value to add to the MIME type

    - #### getCharset

          public java.lang.String getCharset()

      This is used to retrieve the `charset` of this MIME type. This is a special parameter associated with the type, if the parameter is not contained within the type then this will return null, which typically means the default of ISO-8859-1.
      Specified by:
        `getCharset` in interface `ContentType`
      Returns:
        the value that this parameter contains

    - #### getParameter

          public java.lang.String getParameter​(java.lang.String name)

      This is used to retrieve an arbitrary parameter from the MIME type header. This ensures that values for `boundary` or other such parameters are not lost when the header is parsed. This will return the value, unquoted if required, as a string.
      Specified by:
        `getParameter` in interface `ContentType`
      Parameters:
        `name` - this is the name of the parameter to be retrieved
      Returns:
        this is the value for the parameter, or null if empty

    - #### setParameter

          public void setParameter​(java.lang.String name,
                                   java.lang.String value)

      This will add a named parameter to the content type header. If a parameter of the specified name has already been added to the header then that value will be replaced by the new value given. Parameters such as the `boundary` as well as other common parameters can be set with this method.
      Specified by:
        `setParameter` in interface `ContentType`
      Parameters:
        `name` - this is the name of the parameter to be added
        `value` - this is the value to associate with the name

    - #### init

          protected void init()

      This will initialize the parser when it is ready to parse a new `String`. This will reset the parser to a ready state. The init method is invoked by the parser when the `Parser.parse` method is invoked.
      Specified by:
        `init` in class `Parser`

    - #### parse

          protected void parse()

      Reads and parses the MIME type from the given `String` object. This uses the syntax defined by RFC 2616 for the media-type syntax. This parser is only concerned with one parameter, the `charset` parameter. The syntax for the media type is

           media-type = token "/" token *( ";" parameter )
           parameter = token | literal

      Specified by:
        `parse` in class `Parser`

    - #### toString

          public java.lang.String toString()

      This will return the value of the MIME type as a string. This will concatenate the primary and secondary type values and add the `charset` parameter to the type which will recreate the content type.
      Specified by:
        `toString` in interface `ContentType`
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        this returns the string representation of the type