com.openexchange.mail.mime
Class HeaderCollection

java.lang.Object
  com.openexchange.mail.mime.HeaderCollection

All Implemented Interfaces:

java.io.Serializable

public class HeaderCollection
extends java.lang.Object
implements java.io.Serializable

HeaderCollection - Represents a collection of RFC822 headers.

Author:

Thorben Betten

See Also:

Serialized Form

Field Summary

static HeaderCollection

EMPTY_COLLECTION Read-only constant for an empty header collection

Constructor Summary

HeaderCollection()
Initializes a new HeaderCollection with a default initial capacity of 40.

HeaderCollection(HeaderCollection headers)
Copy constructor for HeaderCollection

HeaderCollection(java.io.InputStream inputStream)
Initializes a new HeaderCollection from specified headers' RFC822 input stream

HeaderCollection(int initialCapacity)
Initializes a new HeaderCollection

HeaderCollection(java.lang.String headerSrc)
Initializes a new HeaderCollection from specified headers' RFC822 source

Method Summary

HeaderCollection	addHeader(java.lang.String name, java.lang.String value) Adds a header with the specified name and value The current implementation knows about the preferred order of most well-known headers and will insert headers in that order.
void	addHeaders(HeaderCollection headers) Adds the specified header collection to this header collection.
void	clear() Clears this header collection.
boolean	containsHeader(java.lang.String name) Checks if this header collection contains a header entry for specified header
boolean	equals(java.lang.Object obj) Indicates whether some other object is "equal to" this one.
java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>>	getAllHeaders() Gets an instance of Iterator to iterate all headers.
java.lang.String[]	getHeader(java.lang.String name) Return all the values for the specified header.
java.lang.String	getHeader(java.lang.String name, char delimiter) Get all the headers for this header name, returned as a single String, with headers separated by the delimiter.
java.lang.String	getHeader(java.lang.String name, java.lang.String delimiter) Get all the headers for this header name, returned as a single String, with headers separated by the delimiter.
java.util.Iterator<java.lang.String>	getHeaderNames() Gets an instance of Iterator to iterate all header names.
java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>>	getMatchingHeaders(java.lang.String[] matchingHeaders) Gets the matching headers
java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>>	getNonMatchingHeaders(java.lang.String[] nonMatchingHeaders) Gets the non-matching headers
HeaderCollection	getReadOnlyCollection() Gets a read-only collection constructed from this collection's current content
int	hashCode()
boolean	isEmpty() Returns true if no headers are contained in this collection
void	load(java.io.InputStream inputStream) Read and parse the given headers' RFC822 input stream till the blank line separating the header from the body.
void	load(java.lang.String headerSrc) Read and parse the given headers' RFC822 source till the blank line separating the header from the body.
HeaderCollection	removeHeader(java.lang.String name) Remove all header entries that match the given name
HeaderCollection	setHeader(java.lang.String name, java.lang.String value) Change the first header that matches name to have value, adding a new header if no existing header matches.
int	size() Gets the number of headers contained in this collection.
static void	test() Simple test method
java.lang.String	toString()

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_COLLECTION

public static final HeaderCollection EMPTY_COLLECTION

Read-only constant for an empty header collection

Constructor Detail

HeaderCollection

public HeaderCollection()

Initializes a new HeaderCollection with a default initial capacity of 40.

HeaderCollection

public HeaderCollection(int initialCapacity)

Initializes a new HeaderCollection

Parameters:

initialCapacity - The collection's initial capacity

HeaderCollection

public HeaderCollection(HeaderCollection headers)

Copy constructor for HeaderCollection

Parameters:

headers - The source headers

HeaderCollection

public HeaderCollection(java.lang.String headerSrc)

Initializes a new HeaderCollection from specified headers' RFC822 source

Parameters:

headerSrc - The headers' RFC822 source

HeaderCollection

public HeaderCollection(java.io.InputStream inputStream)
                 throws MailException

Initializes a new HeaderCollection from specified headers' RFC822 input stream

Parameters:

inputStream - The headers' RFC822 input stream

Throws:

MailException - If parsing the header input stream fails

Method Detail

getReadOnlyCollection

public HeaderCollection getReadOnlyCollection()

Gets a read-only collection constructed from this collection's current content

Returns:

A read-only collection

load

public void load(java.io.InputStream inputStream)
          throws MailException

Read and parse the given headers' RFC822 input stream till the blank line separating the header from the body. Thus specified input stream is not closed by this method.

Note that the header lines are added, so any existing headers in this object will not be affected. Headers are added to the end of the existing list of headers, in order.

Provided input stream is not going to be closed but is read until EOF or two subsequent CRLFs occur.

Parameters:

inputStream - The headers' RFC822 input stream

Throws:

MailException - If reading from headers' RFC822 input stream fails

load

public void load(java.lang.String headerSrc)

Read and parse the given headers' RFC822 source till the blank line separating the header from the body.

Note that the header lines are added, so any existing headers in this object will not be affected. Headers are added to the end of the existing list of headers, in order.

Parameters:

headerSrc - The headers' RFC822 source

clear

public void clear()

Clears this header collection.

isEmpty

public boolean isEmpty()

Returns true if no headers are contained in this collection

Returns:

true if no headers are contained in this collection

size

public int size()

Gets the number of headers contained in this collection.

This method is a constant-time operation.

Returns:

The number of headers contained in this collection

addHeaders

public void addHeaders(HeaderCollection headers)

Adds the specified header collection to this header collection.

Note that the header lines are added, so any existing headers in this object will not be affected. Headers are added to the end of the existing list of headers, in order.

Parameters:

headers - The header collection to add

addHeader

public HeaderCollection addHeader(java.lang.String name,
                                  java.lang.String value)

Adds a header with the specified name and value

The current implementation knows about the preferred order of most well-known headers and will insert headers in that order. In addition, it knows that Received headers should be inserted in reverse order (newest before oldest), and that they should appear at the beginning of the headers, preceded only by a possible Return-Path header.

Note that RFC822 headers can only contain US-ASCII characters.

Parameters:

name - The header name

value - The header value

Returns:

This header collection with specified header added

Throws:

java.lang.IllegalArgumentException - If name or value is invalid

setHeader

public HeaderCollection setHeader(java.lang.String name,
                                  java.lang.String value)

Change the first header that matches name to have value, adding a new header if no existing header matches. Remove all matching headers but the first.

Note that RFC822 headers can only contain US-ASCII characters.

Parameters:

name - The header name

value - The header value

Returns:

This header collection with specified header set

Throws:

java.lang.IllegalArgumentException - If name or value is invalid

containsHeader

public boolean containsHeader(java.lang.String name)

Checks if this header collection contains a header entry for specified header

Parameters:

name - The header name

Returns:

true if this header collection contains a header entry for specified header; otherwise false

getHeader

public java.lang.String[] getHeader(java.lang.String name)

Return all the values for the specified header. Returns null if no headers with the specified name exist.

Parameters:

name - The header name

Returns:

An array of header values, or null if none exists

Throws:

java.lang.IllegalArgumentException - If name is invalid

getHeader

public java.lang.String getHeader(java.lang.String name,
                                  java.lang.String delimiter)

Get all the headers for this header name, returned as a single String, with headers separated by the delimiter. If the delimiter is null, only the first header is returned. Returns null if no headers with the specified name exist.

Parameters:

name - The header name

delimiter - The delimiter

Returns:

The value fields for all headers with this name, or null if none

getHeader

public java.lang.String getHeader(java.lang.String name,
                                  char delimiter)

Get all the headers for this header name, returned as a single String, with headers separated by the delimiter. If the delimiter is '\0', only the first header is returned. Returns null if no headers with the specified name exist.

Parameters:

name - The header name

delimiter - The delimiter character

Returns:

The value fields for all headers with this name, or null if none

removeHeader

public HeaderCollection removeHeader(java.lang.String name)

Remove all header entries that match the given name

Parameters:

name - The header name

Returns:

This header collection with specified header removed

getHeaderNames

public java.util.Iterator<java.lang.String> getHeaderNames()

Gets an instance of Iterator to iterate all header names.

Returns:

An instance of Iterator to iterate all header names

getAllHeaders

public java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>> getAllHeaders()

Gets an instance of Iterator to iterate all headers.

Returns:

An instance of Iterator to iterate all headers

getMatchingHeaders

public java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>> getMatchingHeaders(java.lang.String[] matchingHeaders)

Gets the matching headers

Parameters:

matchingHeaders - The matching headers

Returns:

The matching headers

getNonMatchingHeaders

public java.util.Iterator<java.util.Map.Entry<java.lang.String,java.lang.String>> getNonMatchingHeaders(java.lang.String[] nonMatchingHeaders)

Gets the non-matching headers

Parameters:

nonMatchingHeaders - The non-matching headers

Returns:

The non-matching headers

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Indicates whether some other object is "equal to" this one. However this method should be used with care since checking a given header collection for equality with this one requires sorting according to header names and then comparing each header one-by-one. Besides this method behaves exactly as stated in equal method.

Overrides:

equals in class java.lang.Object

Parameters:

obj - The reference object with which to compare.

Returns:

true if this object is the same as the object argument; false otherwise.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

test

public static final void test()

Simple test method