gzz.util
Class HeaderUtil

java.lang.Object
  |
  +--gzz.util.HeaderUtil

public class HeaderUtil
extends java.lang.Object

Utility functions for reading and writing RFC 2822-style headers. The parsing functions in this util are strict in that they don't try to handle non-conformant headers (e.g., headers that use only CR or LF instead of CRLF). They also aren't fully conformant because they do not currently attempt to parse obsoleted syntax, as required by RFC 2822; support for this may be added in the future.

So far, there is no support at all for structured field values.


Nested Class Summary
static class HeaderUtil.ParseException
           
 
Constructor Summary
HeaderUtil()
           
 
Method Summary
static java.lang.String getOne(java.util.Map fields, java.lang.String fieldName)
          Return the value of a single header field, trimmed.
static java.util.Map readHeader(java.io.InputStream in)
          Read the unstructured values of all fields in a header.
static java.lang.String readRaw(java.io.InputStream in)
          Read in the raw header into a String.
static void writeHeader(java.io.OutputStream out, java.util.Collection lines)
          Write a header given a Collection of header fields, inserting CRLF after each one.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

HeaderUtil

public HeaderUtil()
Method Detail

readHeader

public static java.util.Map readHeader(java.io.InputStream in)
                                throws java.io.IOException
Read the unstructured values of all fields in a header. Returns a Map from canonicalized String field names to Collections of Strings representing unstructured field values (with folding removed). For each field name, there is one entry in the corresponding Collection for each time that field appears in the header (this is necessary for supporting e.g. the Received: header field of which more than one instance may appear in a single header). If a field does not appear in the header at all, there is no mapping for its field name in the returned Map.

After this method, in is positioned at the beginning of the message body, after the empty line ending the header.

For a convenient way of extracting the values of header fields which are supposed to occur exactly once, see the getOne() method.

java.io.IOException

readRaw

public static java.lang.String readRaw(java.io.InputStream in)
                                throws java.io.IOException
Read in the raw header into a String.

java.io.IOException

getOne

public static java.lang.String getOne(java.util.Map fields,
                                      java.lang.String fieldName)
                               throws HeaderUtil.ParseException
Return the value of a single header field, trimmed. This takes a fields Map is returned by readHeader(), and extracts the field value of a single header field. The caller assumes that the field appears in the header exactly once; if this is not true, a ParseException is thrown.

For convenience, the returned String is trim()med, i.e., whitespace at the beginning and end is stripped off. If this is not desired, the value has to be extracted from the Map manually.

The fieldName is canonicalized before looking it up in the fields Map.

HeaderUtil.ParseException

writeHeader

public static void writeHeader(java.io.OutputStream out,
                               java.util.Collection lines)
                        throws java.io.IOException
Write a header given a Collection of header fields, inserting CRLF after each one. This is mostly a convenient way of joining together a collection of lines. Additionally, checks are run that the length of each line does not exceed 998 characters, and that no line contains a CR and/or LF character. Folding has to be done outside this method.

The lines are written in the order they're returned by the lines Collection's iterator. lines can simply be a List, but note that when using a SortedSet, the same set of header fields is always turned into the same header (same as in same sequence of bytes)-- no matter in which order the header fields are added to the collection.

Parameters:
lines - A Collection of Strings representing lines to be written into the header. The Strings may not contain line breaks.
java.io.IOException