Package sunlabs.brazil.util.http

Class MimeHeaders

  • public class MimeHeaders
extends StringMap
    This class is build on top of the StringMap class and provides added methods that are of help when manipulating MIME headers. By creating an instance of this class, the user can conveniently read, write, and modify MIME headers.
    Version:
    2.4
    Author:
    Colin Stevens (colin.stevens@sun.com)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int MAX_LINE  
      static int MAX_LINES  

    • Constructor Summary

      Constructors 
      Constructor Description
      MimeHeaders()
      Creates a new, empty MimeHeaders object.
      MimeHeaders​(HttpInputStream in)
      Creates a new MimeHeaders object and then initializes it by reading MIME headers from the specified input stream.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(java.lang.String key, int value)
      Adds a mapping for the given case-insensitive key to the specified value in this MimeHeaders object.
      void copyTo​(MimeHeaders other)
      Copies the contents of this MimeHeaders object, adding all the other's keys and values to the other.
      void print​(java.io.OutputStream out)
      Writes this MimeHeaders object to the given output stream.
      void print​(java.io.PrintStream out)
      Writes this MimeHeaders object to the given output stream.
      void put​(java.lang.String key, int value)
      Maps the given case-insensitive key to the specified value in this MimeHeaders object, replacing the old value.
      void putIfNotPresent​(java.lang.String key, java.lang.String value)
      Maps the given case-insensitive key to the specified value if the key does not already exist in this MimeHeaders object.
      void read​(HttpInputStream in)
      Reads MIME headers from the specified input stream.
      void read​(HttpInputStream in, boolean shouldReplace)
      Reads MIME headers from the specified input stream.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • MimeHeaders

        public MimeHeaders()
        Creates a new, empty MimeHeaders object.

      • MimeHeaders

        public MimeHeaders​(HttpInputStream in)
            throws java.io.IOException
        Creates a new MimeHeaders object and then initializes it by reading MIME headers from the specified input stream.
        Parameters:
        in - The input stream to read.
        Throws:
        java.io.IOException

    • Method Detail

      • read

        public void read​(HttpInputStream in)
          throws java.io.IOException
        Reads MIME headers from the specified input stream. This method reads up to and consumes the blank line that marks the end of the MIME headers. It also stops reading if it reaches the end of the input stream.

        The MIME headers read from the input stream are stored in this MimeHeaders object. All headers read are added to the existing headers; the new headers do not replace the existing ones. The order of the headers in this object will reflect the order of the headers from the input stream, but space characters surrounding the keys and values are not preserved.

        In a set of MIME headers, the given key may appear multiple times (that is, on multiple lines, not necessarily consecutively). In that case, that key will appear multiple times in this MimeHeaders object also. The HTTP spec says that if a given key appears multiple times in a set of MIME headers, the values can be concatenated together with commas between them. However, in practice, it appears that some browsers and HTTP servers get confused when encountering such collapsed MIME headers, for instance, the Yahoo mail reader program.

        MIME headers also support the idea of continuation lines, where a key (and optionally its value) is followed on subsequent line(s) by another value without a key. The HTTP spec says that in this case the values can be concatenated together with space characters between them. In practice, joining continuation lines together does not seem to confuse any browsers or HTTP servers. This method joins continuation lines together by putting the space-equivalent characters "\r\n\t" between the values so it can be easily parsed with StringTokenizer and also easily written to an output stream in a format that actually preserves its formatting as a continuation line.

        Parameters:
        in - The input stream to read from.
        Throws:
        java.io.IOException - if the input stream throws an IOException while being read.

      • read

        public void read​(HttpInputStream in,
                 boolean shouldReplace)
          throws java.io.IOException
        Reads MIME headers from the specified input stream. Same as (@link #read(HttpInputStream in)), only existing keys may be replaced or augmented.
        Parameters:
        in - The input stream to read from.
        shouldReplace - If true, existing keys are replaced instead of augmented.
        Throws:
        java.io.IOException - if the input stream throws an IOException while being read.
        See Also:
        read(HttpInputStream in)

      • print

        public void print​(java.io.OutputStream out)
        Writes this MimeHeaders object to the given output stream. This method does not write a blank line after the headers are written.
        Parameters:
        out - The output stream.

      • print

        public void print​(java.io.PrintStream out)
        Writes this MimeHeaders object to the given output stream. This method does not write a blank line after the headers are written.
        Parameters:
        out - The output stream.

      • putIfNotPresent

        public void putIfNotPresent​(java.lang.String key,
                            java.lang.String value)
        Maps the given case-insensitive key to the specified value if the key does not already exist in this MimeHeaders object.

        Often, when dealing with MIME headers, the user will want to set a header only if that header is not already set.

        Parameters:
        key - The new key. May not be null.
        value - The new value. May be null.

      • put

        public void put​(java.lang.String key,
                int value)
        Maps the given case-insensitive key to the specified value in this MimeHeaders object, replacing the old value.

        This is convenience method that automatically converts the integer value to a string before calling the underlying put method.

        Parameters:
        key - The new key. May not be null.
        value - The new value.

      • add

        public void add​(java.lang.String key,
                int value)
        Adds a mapping for the given case-insensitive key to the specified value in this MimeHeaders object. It leaves any existing key-value mapping alone.

        This is convenience method that automatically converts the integer value to a string before calling the underlying add method.

        Parameters:
        key - The new key. May not be null.
        value - The new value.

      • copyTo

        public void copyTo​(MimeHeaders other)
        Copies the contents of this MimeHeaders object, adding all the other's keys and values to the other.
        Parameters:
        other - The MimeHeaders object to copy to.