Package org.omegazero.http.common

Class HTTPHeaderContainer

java.lang.Object
org.omegazero.common.util.SimpleAttachmentContainer
org.omegazero.http.common.HTTPHeaderContainer
All Implemented Interfaces:
Serializable, org.omegazero.common.util.AttachmentContainer
Direct Known Subclasses:
HTTPMessage, HTTPMessageTrailers
public class HTTPHeaderContainer extends org.omegazero.common.util.SimpleAttachmentContainer implements Serializable
Represents a collection of HTTP header key-value pairs. Each header (key) may have multiple values.

This class is not thread-safe.

Since:
1.2.1
See Also:

  • Field Details

    • headerFields

      protected final Map<String,String[]> headerFields
      Contains the header data. The key is the name of a header field and the value is an array of the values of all header fields with this name. The value array always contains at least one element for any existing header field name.

  • Constructor Details

    • HTTPHeaderContainer

      public HTTPHeaderContainer()
      Creates a new HTTPHeaderContainer with an empty set of headers.

    • HTTPHeaderContainer

      public HTTPHeaderContainer(Map<String,String[]> headers)
      Creates a new HTTPHeaderContainer with the given headers.
      Parameters:
      headers - The headers, or null to create an empty set of headers

    • HTTPHeaderContainer

      public HTTPHeaderContainer(HTTPHeaderContainer headers)
      Copies the given HTTPHeaderContainer.
      Parameters:
      headers - The HTTPHeaderContainer to copy from

  • Method Details

    • getHeader

      public String getHeader(String key)
      Returns the value of a header with the given key (name).
      • If there is no header with the given key, null is returned
      • If there is a single header with the given key, its value is returned
      • If there are multiple headers with the given key, the value of the first header is returned
      A call to this method is equivalent to a call to 
       getHeader(key, 0)
      Parameters:
      key - The name of the HTTP header field to get
      Returns:
      The value of the first header with the given name, or null if none exists
      See Also:

    • getHeader

      public String getHeader(String key, int index)
      Returns the value of a header with the given key (name).

      If multiple header fields with the given name exist, the 0-based index specifies which header to retrieve. This value may be negative, in which case it specifies the offset from the end of the header value list (for example, a value of -1 indicates the last header with the given name). This value is ignored if there are no headers with the given name.

      Parameters:
      key - The name of the HTTP header field to get
      index - The index of the header field to get
      Returns:
      The value of the header with the given name and index, or null if it does not exist
      See Also:

    • getHeader

      public String getHeader(String key, String def)
      Returns the value of a header with the given key (name), or def if no header with the given name exists. See getHeader(String) for more information.
      Parameters:
      key - The name of the HTTP header field to get
      def - A value to return if a header field with the specified name does not exist
      Returns:
      The value of the first header with the given name, or def if none exists
      See Also:

    • getHeader

      public String getHeader(String key, int index, String def)
      Returns the value of a header with the given key (name), or def if it does not exist. See getHeader(String, int) for more information.
      Parameters:
      key - The name of the HTTP header field to get
      index - The index of the header field to get
      def - A value to return if a header field with the specified name and index does not exist
      Returns:
      The value of the header with the given name and index, or def if it does not exist
      See Also:

    • extractHeader

      public String extractHeader(String key)
      Deletes all headers with the given key (name) and returns the value of the first deleted header.
      Parameters:
      key - The name of the HTTP header field(s) to delete
      Returns:
      The previous value of the first header with the given name, or null if it did not exist

    • extractHeaders

      public String[] extractHeaders(String key)
      Deletes all headers with the given key (name) and returns the previous header values. The returned array may have length 0 if no headers with the given name existed.
      Parameters:
      key - The name of the HTTP header field(s) to delete
      Returns:
      The previous value(s) of the header(s) with the given name

    • setHeader

      public void setHeader(String key, String value)
      Sets the value of the header with the given key (name) to the given value. If present, all previous headers with this name are replaced by a single header with the given value, or deleted, if the given value is null.
      Parameters:
      key - The name of the HTTP header field to set
      value - The value of this header field, replacing any previous headers. If null, the header will be deleted

    • editHeader

      public String editHeader(String key, String value, int index)
      Edits an existing header with the given key (name) by setting its value to the given value. The value may be null, in which case the specified header is deleted.

      If multiple header fields with the given name exist, the 0-based index specifies which header to edit. This value may be negative, in which case it specifies the offset from the end of the header value list (for example, a value of -1 indicates the last header with the given name).

      Parameters:
      key - The name of the HTTP header field to edit
      value - The new value of the HTTP header field
      index - The index of the header field to edit
      Returns:
      The previous value of the header
      Throws:
      ArrayIndexOutOfBoundsException - If no header with the given name and index exists
      See Also:

    • addHeader

      public void addHeader(String key, String value)
      Adds a new header with the given key (name) and value to the end of the header list. This, in contrast to setHeader(String, String), preserves any existing headers with the given name.
      Parameters:
      key - The name of the HTTP header field
      value - The new value of the HTTP header field
      See Also:

    • addHeader

      public void addHeader(String key, String value, int index)
      Adds a new header with the given key (name) and value at the given index.

      Any existing header at this index and subsequent headers are moved to the next higher index and other headers are preserved. Unlike other methods in this class, the only negative value the index parameter may have is -1, in which case the new header is added at the end of the list.

      Parameters:
      key - The name of the HTTP header field
      value - The new value of the HTTP header field
      index - The index at which to insert the new header field
      Throws:
      ArrayIndexOutOfBoundsException - If the index is out of range
      See Also:

    • appendHeader

      public void appendHeader(String key, String value)
      Appends the given value to an existing header with the given key (name), separated by ", ", or sets a header with the given value if no such header exists.

      If multiple headers with the given name exist, only the last one is edited.

      A call to this method is equivalent to a call to 

       appendHeader(key, value, ", ", -1)
      Parameters:
      key - The name of the HTTP header field to edit
      value - The value to append to this header field, or the value of the header if it did not exist
      See Also:

    • appendHeader

      public void appendHeader(String key, String value, String separator)
      Appends the given value to an existing header with the given key (name), separated by separator, or sets a header with the given value if no such header exists.

      If multiple headers with the given name exist, only the last one is edited.

      A call to this method is equivalent to a call to 

       appendHeader(key, value, separator, -1)
      Parameters:
      key - The name of the HTTP header field to edit
      value - The value to append to this header field, or the value of the header if it did not exist
      separator - The separator between the existing value and the new value
      See Also:

    • appendHeader

      public void appendHeader(String key, String value, String separator, int index)
      Appends the given value to an existing header with the given key (name), separated by separator, or sets a header with the given value if no such header exists.

      If multiple header fields with the given name exist, the 0-based index specifies which header to edit. This value may be negative, in which case it specifies the offset from the end of the header value list (for example, a value of -1 indicates the last header with the given name). This value is ignored if there are no headers with the given name.

      Parameters:
      key - The name of the HTTP header field to edit
      value - The value to append to this header field, or the value of the header if it did not exist
      separator - The separator between the existing value and the new value
      index - The index of the header field to edit
      Throws:
      ArrayIndexOutOfBoundsException - If there exists at least one header with the given name and index is out of range
      See Also:

    • getHeaderCount

      public int getHeaderCount(String key)
      Returns the number of header fields with the given key (name).
      Parameters:
      key - The name of the HTTP header field to search for
      Returns:
      The number of header fields with the given name

    • headerExists

      public boolean headerExists(String key)
      Checks whether there is at least one header with the given key (name).
      Parameters:
      key - The name of the HTTP header field to search for
      Returns:
      true if a header with the given name exists

    • deleteHeader

      public void deleteHeader(String key)
      Deletes all headers with the given key (name).

      A call to this method is equivalent to a call to 

       setHeader(key, null)
      Parameters:
      key - The name of the HTTP header field to delete

    • deleteHeader

      public String deleteHeader(String key, int index)
      Deletes the header with the given key (name) and index.

      A call to this method is equivalent to a call to 

       editHeader(key, null, index)
      Parameters:
      key - The name of the HTTP header field to delete
      index - The index of the header field to delete
      Returns:
      The previous value of the header

    • headerNameSet

      public Set<String> headerNameSet()
      Returns an unmodifiable set of all header names stored in this HTTPHeaderContainer.
      Returns:
      An unmodifiable set of all header names

    • headerNameCount

      public int headerNameCount()
      Returns the number of unique header names. This may not be the actual number of headers if there are multiple headers with the same name.
      Returns:
      The number of unique header names

    • headerSet

      public Set<Map.Entry<String,String[]>> headerSet()
      Returns an unmodifiable set of all headers stored in this HTTPHeaderContainer.
      Returns:
      An unmodifiable set of all headers

    • headerIterator

      public Iterator<Map.Entry<String,String>> headerIterator()
      Returns an iterator iterating over each header key-value pair. The same keys may occur multiple times if multiple headers with the same name exist.
      Returns:
      The iterator
      See Also:

    • headers

      public Iterable<Map.Entry<String,String>> headers()
      Returns an Iterable for use in a for-each loop. The underlying iterator iterates over each header key-value pair. The same keys may occur multiple times if multiple headers with the same name exist.
      Returns:
      The Iterable
      See Also:

    • checkLocked

      protected void checkLocked()
      May be implemented by subclasses to prevent changing header data in certain situations. This method is called each time an action that would change any header data is about to be performed. To deny this action, this method should throw an IllegalStateException.

    • toString

      public String toString()
      Returns a string representation of this HTTPHeaderContainer, containing all header key-value pairs.
      Overrides:
      toString in class Object

    • fromLegacy

      public static HTTPHeaderContainer fromLegacy(Map<String,String> headerData)
      Creates a HTTPHeaderContainer from the given single-valued header list.
      Parameters:
      headerData - The single-valued header list
      Returns:
      The header data