InternetHeaders is a utility class that manages RFC822 style headers. Given an RFC822 format message stream, it reads lines until the blank line that indicates end of header. The input stream is positioned at the start of the body. The lines are stored within the object and can be extracted as either Strings or javax.mail.Header objects.

This class is mostly intended for service providers. MimeMessage and MimeBody use this class for holding their headers.

A note on RFC822 and MIME headers

RFC822 and MIME header fields must contain only US-ASCII characters. If a header contains non US-ASCII characters, it must be encoded as per the rules in RFC 2047. The MimeUtility class provided in this package can be used to to achieve this. Callers of the setHeader, addHeader, and addHeaderLine methods are responsible for enforcing the MIME requirements for the specified headers. In addition, these header fields must be folded (wrapped) before being sent if they exceed the line length limitation for the transport (1000 bytes for SMTP). Received headers may have been folded. The application is responsible for folding and unfolding headers as appropriate.

The current implementation supports the System property mail.mime.ignorewhitespacelines, which if set to true will cause a line containing only whitespace to be considered a blank line terminating the header.

Modifier and Type	Class and Description
protected static class	InternetHeaders.InternetHeader An individual internet header.
pack-priv static class	InternetHeaders.MatchEnum
pack-priv static class	InternetHeaders.MatchHeaderEnum
pack-priv static class	InternetHeaders.MatchStringEnum

Field Summary

Modifier and Type	Field and Description
protected List<InternetHeaders.InternetHeader>	headers The actual list of Headers, including placeholder entries.
private static final boolean	ignoreWhitespaceLines

Constructor Summary

Access	Constructor and Description
public	InternetHeaders() Create an empty InternetHeaders object.
public	InternetHeaders(InputStream RFC822 input stream is) Read and parse the given RFC822 message stream till the blank line separating the header from the body.
public	InternetHeaders(InputStream RFC822 input stream is, boolean if UTF-8 encoded headers are allowed allowutf8) Read and parse the given RFC822 message stream till the blank line separating the header from the body.

Method Summary

Modifier and Type	Method and Description
public void	addHeader(String header name name, String header value value) Add a header with the specified name and value to the header list.
public void	addHeaderLine(String raw RFC822 header line line) Add an RFC822 header line to the header store.
public Enumeration<String>	Returns: Enumeration of Strings of all header lines getAllHeaderLines() Return all the header lines as an Enumeration of Strings.
public Enumeration<Header>	Returns: Enumeration of Header objects getAllHeaders() Return all the headers as an Enumeration of `javax.mail.Header` objects.
public String[]	Returns: array of header values, or null if none getHeader(String header name name) Return all the values for the specified header.
public String	Returns: the value fields for all headers with this name, or null if none getHeader(String header name name, String delimiter delimiter) Get all the headers for this header name, returned as a single String, with headers separated by the delimiter.
public Enumeration<String>	Returns: Enumeration of Strings of all matching header lines getMatchingHeaderLines(String[] the headers to return names) Return all matching header lines as an Enumeration of Strings.
public Enumeration<Header>	Returns: Enumeration of matching Header objects getMatchingHeaders(String[] the headers to return names) Return all matching `javax.mail.Header` objects.
public Enumeration<String>	Returns: Enumeration of Strings of all non-matching header lines getNonMatchingHeaderLines(String[] the headers to not return names) Return all non-matching header lines
public Enumeration<Header>	Returns: Enumeration of non-matching Header objects getNonMatchingHeaders(String[] the headers to not return names) Return all non-matching `javax.mail.Header` objects.
private static final boolean	isEmpty(String line) Is this line an empty (blank) line?
public void	load(InputStream RFC822 input stream is) Read and parse the given RFC822 message stream till the blank line separating the header from the body.
public void	load(InputStream RFC822 input stream is, boolean if UTF-8 encoded headers are allowed allowutf8) Read and parse the given RFC822 message stream till the blank line separating the header from the body.
public void	removeHeader(String header name name) Remove all header entries that match the given name
public void	setHeader(String header name name, String header value value) Change the first header line that matches name to have value, adding a new header if no existing header matches.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

headers back to summary

headers	back to summary
protected List<InternetHeaders.InternetHeader> headers The actual list of Headers, including placeholder entries. Placeholder entries are Headers with a null value and are never seen by clients of the InternetHeaders class. Placeholder entries are used to keep track of the preferred order of headers. Headers are never actually removed from the list, they're converted into placeholder entries. New headers are added after existing headers of the same name (or before in the case of `Received` and `Return-Path` headers). If no existing header or placeholder for the header is found, new headers are added after the special placeholder with the name ":". Since JavaMail 1.4

protected List<InternetHeaders.InternetHeader> headers

The actual list of Headers, including placeholder entries. Placeholder entries are Headers with a null value and are never seen by clients of the InternetHeaders class. Placeholder entries are used to keep track of the preferred order of headers. Headers are never actually removed from the list, they're converted into placeholder entries. New headers are added after existing headers of the same name (or before in the case of Received and Return-Path headers). If no existing header or placeholder for the header is found, new headers are added after the special placeholder with the name ":".

Since: JavaMail 1.4

ignoreWhitespaceLines	back to summary
private static final boolean ignoreWhitespaceLines

Constructor Detail

InternetHeaders	back to summary
public InternetHeaders() Create an empty InternetHeaders object. Placeholder entries are inserted to indicate the preferred order of headers.

InternetHeaders	back to summary
public InternetHeaders(InputStream is) throws MessagingException Read and parse the given RFC822 message stream till the blank line separating the header from the body. The input stream is left positioned at the start of the body. The header lines are stored internally. For efficiency, wrap a BufferedInputStream around the actual input stream and pass it as the parameter. No placeholder entries are inserted; the original order of the headers is preserved. Parameters is:InputStream RFC822 input stream Exceptions MessagingException: for any I/O error reading the stream

InternetHeaders

back to summary

public InternetHeaders(InputStream is) throws MessagingException

Read and parse the given RFC822 message stream till the blank line separating the header from the body. The input stream is left positioned at the start of the body. The header lines are stored internally.

For efficiency, wrap a BufferedInputStream around the actual input stream and pass it as the parameter.

No placeholder entries are inserted; the original order of the headers is preserved.

Parameters

is:InputStream: RFC822 input stream

Exceptions

MessagingException:: for any I/O error reading the stream

InternetHeaders	back to summary
public InternetHeaders(InputStream is, boolean allowutf8) throws MessagingException Read and parse the given RFC822 message stream till the blank line separating the header from the body. The input stream is left positioned at the start of the body. The header lines are stored internally. For efficiency, wrap a BufferedInputStream around the actual input stream and pass it as the parameter. No placeholder entries are inserted; the original order of the headers is preserved. Parameters is:InputStream RFC822 input stream allowutf8:boolean if UTF-8 encoded headers are allowed Exceptions MessagingException: for any I/O error reading the stream Since JavaMail 1.6

InternetHeaders

back to summary

public InternetHeaders(InputStream is, boolean allowutf8) throws MessagingException

For efficiency, wrap a BufferedInputStream around the actual input stream and pass it as the parameter.

No placeholder entries are inserted; the original order of the headers is preserved.

Parameters

is:InputStream: RFC822 input stream
allowutf8:boolean: if UTF-8 encoded headers are allowed

Exceptions

MessagingException:: for any I/O error reading the stream

Since

JavaMail 1.6

Method Detail

addHeader back to summary

addHeader	back to summary
public void addHeader(String name, String value) Add a header with the specified name and value to the header list. 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, preceeded only by a possible `Return-Path` header. Note that RFC822 headers can only contain US-ASCII characters. Parameters name:String header name value:String header value

public void addHeader(String name, String value)

Add a header with the specified name and value to the header list.

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, preceeded only by a possible Return-Path header.

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

Parameters

name:String: header name
value:String: header value

addHeaderLine	back to summary
public void addHeaderLine(String line) Add an RFC822 header line to the header store. If the line starts with a space or tab (a continuation line), add it to the last header line in the list. Otherwise, append the new header line to the list. Note that RFC822 headers can only contain US-ASCII characters Parameters line:String raw RFC822 header line

addHeaderLine

back to summary

public void addHeaderLine(String line)

Add an RFC822 header line to the header store. If the line starts with a space or tab (a continuation line), add it to the last header line in the list. Otherwise, append the new header line to the list.

Note that RFC822 headers can only contain US-ASCII characters

Parameters

line:String: raw RFC822 header line

getAllHeaderLines	back to summary
public Enumeration<String> getAllHeaderLines() Return all the header lines as an Enumeration of Strings. Returns:Enumeration<String> Enumeration of Strings of all header lines

getAllHeaderLines

back to summary

public Enumeration<String> getAllHeaderLines()

Return all the header lines as an Enumeration of Strings.

Returns:Enumeration<String>: Enumeration of Strings of all header lines

getAllHeaders back to summary

getAllHeaders	back to summary
public Enumeration<Header> getAllHeaders() Return all the headers as an Enumeration of `javax.mail.Header` objects. Returns:Enumeration<Header> Enumeration of Header objects

public Enumeration<Header> getAllHeaders()

Return all the headers as an Enumeration of javax.mail.Header objects.

Returns:Enumeration<Header>: Enumeration of Header objects

getHeader back to summary

getHeader	back to summary
public String[] getHeader(String name) Return all the values for the specified header. The values are String objects. Returns `null` if no headers with the specified name exist. Parameters name:String header name Returns:String[] array of header values, or null if none

public String[] getHeader(String name)

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

Parameters

name:String: header name

Returns:String[]

array of header values, or null if none

getHeader back to summary

getHeader	back to summary
public String getHeader(String name, 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:String header name delimiter:String delimiter Returns:String the value fields for all headers with this name, or null if none

public String getHeader(String name, 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:String: header name
delimiter:String: delimiter

Returns:String

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

getMatchingHeaderLines	back to summary
public Enumeration<String> getMatchingHeaderLines(String[] names) Return all matching header lines as an Enumeration of Strings. Parameters names:String[] the headers to return Returns:Enumeration<String> Enumeration of Strings of all matching header lines

getMatchingHeaderLines

back to summary

public Enumeration<String> getMatchingHeaderLines(String[] names)

Return all matching header lines as an Enumeration of Strings.

Parameters

names:String[]: the headers to return

Returns:Enumeration<String>

Enumeration of Strings of all matching header lines

getMatchingHeaders back to summary

getMatchingHeaders	back to summary
public Enumeration<Header> getMatchingHeaders(String[] names) Return all matching `javax.mail.Header` objects. Parameters names:String[] the headers to return Returns:Enumeration<Header> Enumeration of matching Header objects

public Enumeration<Header> getMatchingHeaders(String[] names)

Return all matching javax.mail.Header objects.

Parameters

names:String[]: the headers to return

Returns:Enumeration<Header>

Enumeration of matching Header objects

getNonMatchingHeaderLines	back to summary
public Enumeration<String> getNonMatchingHeaderLines(String[] names) Return all non-matching header lines Parameters names:String[] the headers to not return Returns:Enumeration<String> Enumeration of Strings of all non-matching header lines

getNonMatchingHeaderLines

back to summary

public Enumeration<String> getNonMatchingHeaderLines(String[] names)

Return all non-matching header lines

Parameters

names:String[]: the headers to not return

Returns:Enumeration<String>

Enumeration of Strings of all non-matching header lines

getNonMatchingHeaders back to summary

getNonMatchingHeaders	back to summary
public Enumeration<Header> getNonMatchingHeaders(String[] names) Return all non-matching `javax.mail.Header` objects. Parameters names:String[] the headers to not return Returns:Enumeration<Header> Enumeration of non-matching Header objects

public Enumeration<Header> getNonMatchingHeaders(String[] names)

Return all non-matching javax.mail.Header objects.

Parameters

names:String[]: the headers to not return

Returns:Enumeration<Header>

Enumeration of non-matching Header objects

isEmpty	back to summary
private static final boolean isEmpty(String line) Is this line an empty (blank) line?

load	back to summary
public void load(InputStream is) throws MessagingException Read and parse the given RFC822 message stream till the blank line separating the header from the body. Store the header lines inside this InternetHeaders object. The order of header lines is preserved. Note that the header lines are added into this InternetHeaders object, 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 is:InputStream RFC822 input stream Exceptions MessagingException: for any I/O error reading the stream

load

back to summary

public void load(InputStream is) throws MessagingException

Read and parse the given RFC822 message stream till the blank line separating the header from the body. Store the header lines inside this InternetHeaders object. The order of header lines is preserved.

Note that the header lines are added into this InternetHeaders object, 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

is:InputStream: RFC822 input stream

Exceptions

MessagingException:: for any I/O error reading the stream

load	back to summary
public void load(InputStream is, boolean allowutf8) throws MessagingException Read and parse the given RFC822 message stream till the blank line separating the header from the body. Store the header lines inside this InternetHeaders object. The order of header lines is preserved. Note that the header lines are added into this InternetHeaders object, 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 is:InputStream RFC822 input stream allowutf8:boolean if UTF-8 encoded headers are allowed Exceptions MessagingException: for any I/O error reading the stream Since JavaMail 1.6

load

back to summary

public void load(InputStream is, boolean allowutf8) throws MessagingException

Parameters

is:InputStream: RFC822 input stream
allowutf8:boolean: if UTF-8 encoded headers are allowed

Exceptions

MessagingException:: for any I/O error reading the stream

Since

JavaMail 1.6

removeHeader	back to summary
public void removeHeader(String name) Remove all header entries that match the given name Parameters name:String header name

removeHeader

back to summary

public void removeHeader(String name)

Remove all header entries that match the given name

Parameters

name:String: header name

setHeader	back to summary
public void setHeader(String name, String value) Change the first header line 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:String header name value:String header value

setHeader

back to summary

public void setHeader(String name, String value)

Change the first header line 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:String: header name
value:String: header value

javax.mail.internet back to summary

protected final Class InternetHeaders.InternetHeader

Class Inheritance

extends Header

java.lang.Object
javax.mail.Header
javax.mail.internet.InternetHeaders.InternetHeader

An individual internet header. This class is only used by subclasses of InternetHeaders.

An InternetHeader object with a null value is used as a placeholder for headers of that name, to preserve the order of headers. A placeholder InternetHeader object with a name of ":" marks the location in the list of headers where new headers are added by default.

Since: JavaMail 1.4

Field Summary

Modifier and Type	Field and Description
pack-priv String	line

Inherited from javax.mail.Header:: name value

Constructor Summary

Access	Constructor and Description
public	InternetHeader(String the header line l) Constructor that takes a line and splits out the header name.
public	InternetHeader(String the name of the header n, String the value of the header v) Constructor that takes a header name and value.

Method Summary

Modifier and Type	Method and Description
public String	getValue() Overrides javax.mail.Header.getValue. Return the "value" part of the header line.

Inherited from javax.mail.Header:: getName

Field Detail

line	back to summary
pack-priv String line

Constructor Detail

InternetHeader	back to summary
public InternetHeader(String l) Constructor that takes a line and splits out the header name. Parameters l:String the header line

InternetHeader

back to summary

public InternetHeader(String l)

Constructor that takes a line and splits out the header name.

Parameters

l:String: the header line

InternetHeader	back to summary
public InternetHeader(String n, String v) Constructor that takes a header name and value. Parameters n:String the name of the header v:String the value of the header

InternetHeader

back to summary

public InternetHeader(String n, String v)

Constructor that takes a header name and value.

Parameters

n:String: the name of the header
v:String: the value of the header

Method Detail

getValue	back to summary
public String getValue() Overrides javax.mail.Header.getValue. Return the "value" part of the header line. Returns:String Doc from javax.mail.Header.getValue. value of the header Annotations @Override

getValue

back to summary

public String getValue()

Overrides javax.mail.Header.getValue.

Return the "value" part of the header line.

Returns:String

Doc from javax.mail.Header.getValue.

value of the header

Annotations

@Override

javax.mail.internet back to summary

pack-priv Class InternetHeaders.MatchEnum

Class Inheritance

extends Object

java.lang.Object
javax.mail.internet.InternetHeaders.MatchEnum

Known Direct Subclasses

javax.mail.internet.InternetHeaders.MatchStringEnum, javax.mail.internet.InternetHeaders.MatchHeaderEnum

Field Summary

Modifier and Type	Field and Description
private Iterator<InternetHeaders.InternetHeader>	e
private boolean	match
private String[]	names
private InternetHeaders.InternetHeader	next_header
private boolean	want_line

Constructor Summary

Access	Constructor and Description
pack-priv	MatchEnum(List<InternetHeaders.InternetHeader> v, String[] n, boolean m, boolean l)

Method Summary

Modifier and Type	Method and Description
public boolean	hasMoreElements()
public Object	nextElement()
private InternetHeaders.InternetHeader	nextMatch()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

e	back to summary
private Iterator<InternetHeaders.InternetHeader> e

match	back to summary
private boolean match

names	back to summary
private String[] names

next_header	back to summary
private InternetHeaders.InternetHeader next_header

want_line	back to summary
private boolean want_line

Constructor Detail

MatchEnum	back to summary
pack-priv MatchEnum(List<InternetHeaders.InternetHeader> v, String[] n, boolean m, boolean l)

Method Detail

hasMoreElements	back to summary
public boolean hasMoreElements()

nextElement	back to summary
public Object nextElement()

nextMatch	back to summary
private InternetHeaders.InternetHeader nextMatch()

javax.mail.internet back to summary

pack-priv Class InternetHeaders.MatchHeaderEnum

Class Inheritance

extends MatchEnum
implements Enumeration<Header>

java.lang.Object
javax.mail.internet.InternetHeaders.MatchEnum
javax.mail.internet.InternetHeaders.MatchHeaderEnum

All Implemented Interfaces

java.util.Enumeration

Constructor Summary

Access	Constructor and Description
pack-priv	MatchHeaderEnum(List<InternetHeaders.InternetHeader> v, String[] n, boolean m)

Method Summary

Modifier and Type	Method and Description
public Header	nextElement() Overrides javax.mail.internet.InternetHeaders.MatchEnum.nextElement. Implements java.util.Enumeration.nextElement. Returns the next element of this enumeration if this enumeration object has at least one more element to provide.

Inherited from javax.mail.internet.InternetHeaders.MatchEnum:: hasMoreElements

Constructor Detail

MatchHeaderEnum	back to summary
pack-priv MatchHeaderEnum(List<InternetHeaders.InternetHeader> v, String[] n, boolean m)

Method Detail

nextElement	back to summary
public Header nextElement() Overrides javax.mail.internet.InternetHeaders.MatchEnum.nextElement. Implements java.util.Enumeration.nextElement. Doc from java.util.Enumeration.nextElement. Returns the next element of this enumeration if this enumeration object has at least one more element to provide. Returns:Header the next element of this enumeration. Annotations @Override

nextElement

back to summary

public Header nextElement()

Overrides javax.mail.internet.InternetHeaders.MatchEnum.nextElement.

Implements java.util.Enumeration.nextElement.

Doc from java.util.Enumeration.nextElement.

Returns the next element of this enumeration if this enumeration object has at least one more element to provide.

Returns:Header

the next element of this enumeration.

Annotations

@Override

javax.mail.internet back to summary

pack-priv Class InternetHeaders.MatchStringEnum

Class Inheritance

extends MatchEnum
implements Enumeration<String>

java.lang.Object
javax.mail.internet.InternetHeaders.MatchEnum
javax.mail.internet.InternetHeaders.MatchStringEnum

All Implemented Interfaces

java.util.Enumeration

Constructor Summary

Access	Constructor and Description
pack-priv	MatchStringEnum(List<InternetHeaders.InternetHeader> v, String[] n, boolean m)

Method Summary

Modifier and Type	Method and Description
public String	nextElement() Overrides javax.mail.internet.InternetHeaders.MatchEnum.nextElement. Implements java.util.Enumeration.nextElement. Returns the next element of this enumeration if this enumeration object has at least one more element to provide.

Inherited from javax.mail.internet.InternetHeaders.MatchEnum:: hasMoreElements

Constructor Detail

MatchStringEnum	back to summary
pack-priv MatchStringEnum(List<InternetHeaders.InternetHeader> v, String[] n, boolean m)

Method Detail

nextElement

back to summary

public String nextElement()

Overrides javax.mail.internet.InternetHeaders.MatchEnum.nextElement.

Implements java.util.Enumeration.nextElement.

Doc from java.util.Enumeration.nextElement.

Returns the next element of this enumeration if this enumeration object has at least one more element to provide.

Returns:String

the next element of this enumeration.

Annotations

@Override

public Class InternetHeaders

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

protected final Class InternetHeaders.InternetHeader

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv Class InternetHeaders.MatchEnum

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

pack-priv Class InternetHeaders.MatchHeaderEnum

Constructor Summary

Method Summary

Constructor Detail

Method Detail

pack-priv Class InternetHeaders.MatchStringEnum

Constructor Summary

Method Summary

Constructor Detail

Method Detail