MimeHeaders (Apache Tomcat 10.1.20 API Documentation)
Description: declaration: package: org.apache.tomcat.util.http, class: MimeHeaders

Package org.apache.tomcat.util.http

# Class MimeHeaders

java.lang.Object
org.apache.tomcat.util.http.MimeHeaders

public class MimeHeaders extends Object
Memory-efficient repository for Mime Headers. When the object is recycled, it will keep the allocated headers[] and all the MimeHeaderField - no GC is generated.

For input headers it is possible to use the MessageByte for Fields - so no GC will be generated.

The only garbage is generated when using the String for header names/values - this can't be avoided when the servlet calls header methods, but is easy to avoid inside tomcat. The goal is to use _only_ MessageByte-based Fields, and reduce to 0 the memory overhead of tomcat.

This class is used to contain standard internet message headers, used for SMTP (RFC822) and HTTP (RFC2068) messages as well as for MIME (RFC 2045) applications such as transferring typed data and grouping related items in multipart message bodies.

Message headers, as specified in RFC822, include a field name and a field body. Order has no semantic significance, and several fields with the same name may exist. However, most fields do not (and should not) exist more than once in a header.

Many kinds of field body must conform to a specified syntax, including the standard parenthesized comment syntax. This class supports only two simple syntaxes, for dates and integers.

When processing headers, care must be taken to handle the case of multiple same-name fields correctly. The values of such fields are only available as strings. They may be accessed by index (treating the header as an array of fields), or by name (returning an array of string values).

Headers are first parsed and stored in the order they are received. This is based on the fact that most servlets will not directly access all headers, and most headers are single-valued. (the alternative - a hash or similar data structure - will add an overhead that is not needed in most cases)

Apache seems to be using a similar method for storing and manipulating headers.

Author:
  dac@eng.sun.com, James Todd [gonzo@eng.sun.com], Costin Manolache, kevin seguin

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_HEADER_SIZE`
  Initial size - should be == average number of headers per request

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `MimeHeaders()`
  Creates a new MimeHeaders object using a default buffer size.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `MessageBytes`
  `addValue(byte[] b, int startN, int len)`
  Create a new named header using un-translated byte[].
  `MessageBytes`
  `addValue(String name)`
  Create a new named header , return the MessageBytes container for the new value
  `void`
  `clear()`
  Deprecated.
  `void`
  `duplicate(MimeHeaders source)`
  `int`
  `findHeader(String name, int starting)`
  Find the index of a header with the given name.
  `String`
  `getHeader(String name)`
  `MessageBytes`
  `getName(int n)`
  `MessageBytes`
  `getUniqueValue(String name)`
  Finds and returns a unique header field with the given name.
  `MessageBytes`
  `getValue(int n)`
  `MessageBytes`
  `getValue(String name)`
  Finds and returns a header field with the given name.
  `Enumeration<String>`
  `names()`
  Returns an enumeration of strings representing the header field names.
  `void`
  `recycle()`
  Clears all header fields.
  `void`
  `removeHeader(int idx)`
  Reset, move to the end and then reduce count by 1.
  `void`
  `removeHeader(String name)`
  Removes a header field with the specified name.
  `void`
  `setLimit(int limit)`
  Set limit on the number of header fields.
  `MessageBytes`
  `setValue(String name)`
  Allow "set" operations, which removes all current values for this header.
  `int`
  `size()`
  `String`
  `toString()`
  `Enumeration<String>`
  `values(String name)`

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

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

- ## Field Details

  - ### DEFAULT_HEADER_SIZE

    public static final int DEFAULT_HEADER_SIZE
    Initial size - should be == average number of headers per request
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### MimeHeaders

    public MimeHeaders()
    Creates a new MimeHeaders object using a default buffer size.

- ## Method Details

  - ### setLimit

    public void setLimit(int limit)
    Set limit on the number of header fields.
    Parameters:
      `limit` - The new limit

  - ### recycle

    public void recycle()
    Clears all header fields.

  - ### clear

    @Deprecated public void clear()
    Deprecated.

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### duplicate

    public void duplicate(MimeHeaders source) throws IOException
    Throws:
      `IOException`

  - ### size

    public int size()
    Returns:
      the current number of header fields.

  - ### getName

    public MessageBytes getName(int n)
    Parameters:
      `n` - The header index
    Returns:
      the Nth header name, or null if there is no such header. This may be used to iterate through all header fields.

  - ### getValue

    public MessageBytes getValue(int n)
    Parameters:
      `n` - The header index
    Returns:
      the Nth header value, or null if there is no such header. This may be used to iterate through all header fields.

  - ### findHeader

    public int findHeader(String name, int starting)
    Find the index of a header with the given name.
    Parameters:
      `name` - The header name
      `starting` - Index on which to start looking
    Returns:
      the header index

  - ### names

    public Enumeration<String> names()
    Returns an enumeration of strings representing the header field names. Field names may appear multiple times in this enumeration, indicating that multiple fields with that name exist in this header.
    Returns:
      the enumeration

  - ### values

    public Enumeration<String> values(String name)

  - ### addValue

    public MessageBytes addValue(String name)
    Create a new named header , return the MessageBytes container for the new value
    Parameters:
      `name` - The header name
    Returns:
      the message bytes container for the value

  - ### addValue

    public MessageBytes addValue(byte[] b, int startN, int len)
    Create a new named header using un-translated byte[]. The conversion to chars can be delayed until encoding is known.
    Parameters:
      `b` - The header name bytes
      `startN` - Offset
      `len` - Length
    Returns:
      the message bytes container for the value

  - ### setValue

    public MessageBytes setValue(String name)
    Allow "set" operations, which removes all current values for this header.
    Parameters:
      `name` - The header name
    Returns:
      the message bytes container for the value

  - ### getValue

    public MessageBytes getValue(String name)
    Finds and returns a header field with the given name. If no such field exists, null is returned. If more than one such field is in the header, an arbitrary one is returned.
    Parameters:
      `name` - The header name
    Returns:
      the value

  - ### getUniqueValue

    public MessageBytes getUniqueValue(String name)
    Finds and returns a unique header field with the given name. If no such field exists, null is returned. If the specified header field is not unique then an `IllegalArgumentException` is thrown.
    Parameters:
      `name` - The header name
    Returns:
      the value if unique
    Throws:
      `IllegalArgumentException` - if the header has multiple values

  - ### getHeader

    public String getHeader(String name)

  - ### removeHeader

    public void removeHeader(String name)
    Removes a header field with the specified name. Does nothing if such a field could not be found.
    Parameters:
      `name` - the name of the header field to be removed

  - ### removeHeader

    public void removeHeader(int idx)
    Reset, move to the end and then reduce count by 1.
    Parameters:
      `idx` - the index of the header to remove.