com.hunnysoft.jmime
Class Headers

java.lang.Object
  com.hunnysoft.jmime.Node
      com.hunnysoft.jmime.Headers

All Implemented Interfaces:

java.lang.Cloneable

public class Headers

extends Node

Class that represents the collection of header fields in a message or body part.

Headers represents the collection of header fields (often called just headers) in an entity (either a message or body part), as described in RFC 2822 and RFC 2045. A Headers object manages a list of Field objects, which represent the individual header fields.

In the document tree representation of a message, a Headers object is an intermediate node, having both a parent node and several child nodes. The parent node is the Entity object that contains it. The child nodes are the Field objects in the list it manages. (See the overview section in the reference page for Node for a discussion of the tree representation of a message.)

Normally, you do not create a Headers object directly, but you access it through the Entity.headers() method of Entity, which creates the Headers object for you.

You may use public methods in Headers for adding, removing, or accessing the Field objects it contains. Alternatively, you may use the convenience methods Headers provides. You may call the methods to(), from(), contentType(), and other similar methods to directly access the field bodies of the most common structured headers fields. These methods also create Field and FieldBody objects if necessary. For example, if you call to() to access the To header field body, and the To header field does not exist, the method creates it for you. You may call hasField(String) to check if a particular header field exists. For example, to check if the Content-Type header field exists, call the method hasField("Content-Type"). You may call fieldBody(String) to directly access the field body of any header field. If the field does not exist, fieldBody(String) creates it.

Field Summary

static java.lang.String	BCC String constant containing "Bcc".
static java.lang.String	CC String constant containing "Cc".
static java.lang.String	COMMENTS String constant containing "Comments".
static java.lang.String	CONTENT_DESCRIPTION String constant containing "Content-Description".
static java.lang.String	CONTENT_DISPOSITION String constant containing "Content-Disposition".
static java.lang.String	CONTENT_ID String constant containing "Content-ID".
static java.lang.String	CONTENT_LANGUAGE String constant containing "Content-Language".
static java.lang.String	CONTENT_TRANSFER_ENCODING String constant containing "Content-Transfer-Encoding".
static java.lang.String	CONTENT_TYPE String constant containing "Content-Type".
static java.lang.String	DATE String constant containing "Date".
static java.lang.String	FROM String constant containing "From".
static java.lang.String	IN_REPLY_TO String constant containing "In-Reply-To".
static java.lang.String	KEYWORDS String constant containing "Keywords".
static java.lang.String	MESSAGE_ID String constant containing "Message-ID".
static java.lang.String	MIME_VERSION String constant containing "MIME-Version".
static java.lang.String	RECEIVED String constant containing "Received".
static java.lang.String	REFERENCES String constant containing "References".
static java.lang.String	REPLY_TO String constant containing "Reply-To".
static java.lang.String	RESENT_BCC String constant containing "Resent-Bcc".
static java.lang.String	RESENT_CC String constant containing "Resent-Cc".
static java.lang.String	RESENT_DATE String constant containing "Resent-Date".
static java.lang.String	RESENT_FROM String constant containing "Resent-From".
static java.lang.String	RESENT_MESSAGE_ID String constant containing "Resent-Message-ID".
static java.lang.String	RESENT_REPLY_TO String constant containing "Resent-Reply-To".
static java.lang.String	RESENT_SENDER String constant containing "Resent-Sender".
static java.lang.String	RESENT_TO String constant containing "Resent-To".
static java.lang.String	RETURN_PATH String constant containing "Return-Path".
static java.lang.String	SENDER String constant containing "Sender".
static java.lang.String	SUBJECT String constant containing "Subject".
static java.lang.String	TO String constant containing "To".

Fields inherited from class com.hunnysoft.jmime.Node

mIsModified, mParent, mString

Constructor Summary

Headers()
Default constructor.

Headers(ByteString bstr)
Constructor that takes an initial byte string argument.

Headers(Headers other)
Copy constructor.

Method Summary

void	addField(Field field) Adds a header field to the end of the list.
void	assemble() Assembles the string representation.
AddressList	bcc() Gets the field body of the Bcc header field.
AddressList	cc() Gets the field body of the Cc header field.
java.lang.Object	clone() Creates a copy of this object.
DispositionType	contentDisposition() Gets the field body of the Content-Disposition header field.
MsgId	contentId() Gets the field body of the Content-ID header field.
TransferEncodingType	contentTransferEncoding() Gets the field body of the Content-Transfer-Encoding header field.
MediaType	contentType() Gets the field body of the Content-Type header field.
DateTime	date() Gets the field body of the Date header field.
void	deleteAllFields() Deletes all header fields in the list.
Field	fieldAt(int index) Gets the header field at the specified position.
FieldBody	fieldBody(java.lang.String name) Gets the field body of the specified header field.
protected Field	findFieldNamed(java.lang.String name) Searches for a header field by its field name.
AddressList	from() Gets the field body of the From header field.
boolean	hasField(java.lang.String name) Returns true if a field with the specified name is in the list.
void	insertFieldAt(int index, Field field) Inserts a header field at the specified position.
MsgId	messageId() Gets the field body of the Message-ID header field.
int	numFields() Gets the number of header fields in the list.
void	parse() Parses the string representation.
Stamp	received() Gets the field body of the Received header field.
Field	removeFieldAt(int index) Removes the header field at the specified position.
AddressList	replyTo() Gets the field body of the Reply-To header field.
Mailbox	returnPath() Gets the field body of the Return-Path header field.
Mailbox	sender() Gets the field body of the Sender header field.
Text	subject() Gets the field body of the Subject header field.
AddressList	to() Gets the field body of the To header field.

Methods inherited from class com.hunnysoft.jmime.Node

_setString, isModified, parent, setModified, setParent, setString, string, toString

Methods inherited from class java.lang.Object

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

Field Detail

BCC

public static final java.lang.String BCC

String constant containing "Bcc".

See Also:

Constant Field Values

CC

public static final java.lang.String CC

String constant containing "Cc".

See Also:

Constant Field Values

COMMENTS

public static final java.lang.String COMMENTS

String constant containing "Comments".

See Also:

Constant Field Values

DATE

public static final java.lang.String DATE

String constant containing "Date".

See Also:

Constant Field Values

FROM

public static final java.lang.String FROM

String constant containing "From".

See Also:

Constant Field Values

IN_REPLY_TO

public static final java.lang.String IN_REPLY_TO

String constant containing "In-Reply-To".

See Also:

Constant Field Values

KEYWORDS

public static final java.lang.String KEYWORDS

String constant containing "Keywords".

See Also:

Constant Field Values

MESSAGE_ID

public static final java.lang.String MESSAGE_ID

String constant containing "Message-ID".

See Also:

Constant Field Values

RECEIVED

public static final java.lang.String RECEIVED

String constant containing "Received".

See Also:

Constant Field Values

REFERENCES

public static final java.lang.String REFERENCES

String constant containing "References".

See Also:

Constant Field Values

REPLY_TO

public static final java.lang.String REPLY_TO

String constant containing "Reply-To".

See Also:

Constant Field Values

RESENT_BCC

public static final java.lang.String RESENT_BCC

String constant containing "Resent-Bcc".

See Also:

Constant Field Values

RESENT_CC

public static final java.lang.String RESENT_CC

String constant containing "Resent-Cc".

See Also:

Constant Field Values

RESENT_DATE

public static final java.lang.String RESENT_DATE

String constant containing "Resent-Date".

See Also:

Constant Field Values

RESENT_FROM

public static final java.lang.String RESENT_FROM

String constant containing "Resent-From".

See Also:

Constant Field Values

RESENT_MESSAGE_ID

public static final java.lang.String RESENT_MESSAGE_ID

String constant containing "Resent-Message-ID".

See Also:

Constant Field Values

RESENT_REPLY_TO

public static final java.lang.String RESENT_REPLY_TO

String constant containing "Resent-Reply-To".

See Also:

Constant Field Values

RESENT_SENDER

public static final java.lang.String RESENT_SENDER

String constant containing "Resent-Sender".

See Also:

Constant Field Values

RESENT_TO

public static final java.lang.String RESENT_TO

String constant containing "Resent-To".

See Also:

Constant Field Values

RETURN_PATH

public static final java.lang.String RETURN_PATH

String constant containing "Return-Path".

See Also:

Constant Field Values

SENDER

public static final java.lang.String SENDER

String constant containing "Sender".

See Also:

Constant Field Values

SUBJECT

public static final java.lang.String SUBJECT

String constant containing "Subject".

See Also:

Constant Field Values

TO

public static final java.lang.String TO

String constant containing "To".

See Also:

Constant Field Values

CONTENT_DESCRIPTION

public static final java.lang.String CONTENT_DESCRIPTION

String constant containing "Content-Description".

See Also:

Constant Field Values

CONTENT_ID

public static final java.lang.String CONTENT_ID

String constant containing "Content-ID".

See Also:

Constant Field Values

CONTENT_TRANSFER_ENCODING

public static final java.lang.String CONTENT_TRANSFER_ENCODING

String constant containing "Content-Transfer-Encoding".

See Also:

Constant Field Values

CONTENT_TYPE

public static final java.lang.String CONTENT_TYPE

String constant containing "Content-Type".

See Also:

Constant Field Values

CONTENT_LANGUAGE

public static final java.lang.String CONTENT_LANGUAGE

String constant containing "Content-Language".

See Also:

Constant Field Values

MIME_VERSION

public static final java.lang.String MIME_VERSION

String constant containing "MIME-Version".

See Also:

Constant Field Values

CONTENT_DISPOSITION

public static final java.lang.String CONTENT_DISPOSITION

String constant containing "Content-Disposition".

See Also:

Constant Field Values

Constructor Detail

Headers

public Headers()

Default constructor.

This constructor sets the Headers object's string representation to the empty string and sets its parent node to null.

Headers

public Headers(Headers other)

Copy constructor.

This constructor performs a deep copy of its argument. The parent node of the new Headers object is set to null.

Parameters:

other - Headers instance to copy

Headers

public Headers(ByteString bstr)

Constructor that takes an initial byte string argument.

This constructor sets the Headers object's string representation to bstr and sets its parent node to null.

Normally, you call the parse() method immediately after this constructor to create the broken-down representation.

Parameters:

bstr - initial value for the string representation

Method Detail

clone

public java.lang.Object clone()

Creates a copy of this object.

This method, inherited from Object, creates a new Headers object that has the same value as this Headers object. The parent node of the new Headers object is set to null.

Overrides:

clone in class Node

Returns:

a copy of this object

parse

public void parse()

Parses the string representation.

This method, inherited from Node, executes the parse operation for Headers objects. The parse operation creates or updates the broken-down representation from the string representation. For Headers objects, the parse operation parses the string representation to create a list of Field objects. This method also calls the parse() method of each Field object in its list.

You should call this method after you set or modify the string representation, and before you access any of the contained Field objects.

This method clears the is-modified flag.

Specified by:

parse in class Node

See Also:

Node.assemble()

assemble

public void assemble()

Assembles the string representation.

This method, inherited from Node, executes the assemble operation for Headers objects. The assemble operation creates or updates the string representation from the broken-down representation. For Headers objects, the assemble operation builds the string representation from its list of Field objects. Before it builds the string representation for the Headers object, this method first calls the assemble() method of each Field object in its list.

You should call this method after you set or modify any of the contained Field objects, and before you retrieve the string representation.

This method clears the is-modified flag.

Specified by:

assemble in class Node

See Also:

Node.parse()

numFields

public int numFields()

Gets the number of header fields in the list.

Returns:

number of Field objects in the list

addField

public void addField(Field field)

Adds a header field to the end of the list.

Parameters:

field - Field object to add

deleteAllFields

public void deleteAllFields()

Deletes all header fields in the list.

fieldAt

public Field fieldAt(int index)

Gets the header field at the specified position.

Parameters:

index - position of the Field object to get (0 <= index < numFields())

Returns:

Field object at the specified position

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range

insertFieldAt

public void insertFieldAt(int index,
                          Field field)

Inserts a header field at the specified position.

Inserting at position 0 inserts the field at the beginning. Inserting at position numFields() appends the field to the end.

Parameters:

index - position in list to insert the Field object (0 <= index <= numFields())

field - Field object to insert

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range

removeFieldAt

public Field removeFieldAt(int index)

Removes the header field at the specified position.

Parameters:

index - position of the Field object to remove (0 <= index < numFields())

Returns:

the removed Field object

Throws:

java.lang.IndexOutOfBoundsException - if index is out of range

hasField

public boolean hasField(java.lang.String name)

Returns true if a field with the specified name is in the list.

    if (headers.hasField("Received") {
         // ...
    }
 

Parameters:

name - name of the field to search for

Returns:

true if the specified field is present

fieldBody

public FieldBody fieldBody(java.lang.String name)

Gets the field body of the specified header field.

If the header field does not exist, the method creates it. You may call hasField(String) to test if the header field exists without creating it.

For most standard structured header fields, Headers provides convenience methods for directly accessing those fields. For example, to access the To header field, you may call the {link #to} method, which returns an AddressList object. You may call fieldBody(String) to access the field body of unstructured header fields or less common header fields.

Parameters:

name - name of the field to retrieve

Returns:

reference to the FieldBody for the specified field

bcc

public AddressList bcc()

Gets the field body of the Bcc header field.

If the field does not exist, the method creates it.

cc

public AddressList cc()

Gets the field body of the Cc header field.

If the field does not exist, the method creates it.

date

public DateTime date()

Gets the field body of the Date header field.

If the field does not exist, the method creates it.

from

public AddressList from()

Gets the field body of the From header field.

If the field does not exist, the method creates it.

messageId

public MsgId messageId()

Gets the field body of the Message-ID header field.

If the field does not exist, the method creates it.

received

public Stamp received()

Gets the field body of the Received header field.

If the field does not exist, the method creates it.

replyTo

public AddressList replyTo()

Gets the field body of the Reply-To header field.

If the field does not exist, the method creates it.

returnPath

public Mailbox returnPath()

Gets the field body of the Return-Path header field.

If the field does not exist, the method creates it.

sender

public Mailbox sender()

Gets the field body of the Sender header field.

If the field does not exist, the method creates it.

subject

public Text subject()

Gets the field body of the Subject header field.

If the field does not exist, the method creates it.

to

public AddressList to()

Gets the field body of the To header field.

If the field does not exist, the method creates it.

contentDisposition

public DispositionType contentDisposition()

Gets the field body of the Content-Disposition header field.

If the field does not exist, the method creates it.

contentId

public MsgId contentId()

Gets the field body of the Content-ID header field.

If the field does not exist, the method creates it.

contentTransferEncoding

public TransferEncodingType contentTransferEncoding()

Gets the field body of the Content-Transfer-Encoding header field.

If the field does not exist, the method creates it.

contentType

public MediaType contentType()

Gets the field body of the Content-Type header field.

If the field does not exist, method creates it.

findFieldNamed

protected Field findFieldNamed(java.lang.String name)

Searches for a header field by its field name.

If the field is not found, the method returns null.

Parameters:

name - name of the field to search for

Returns:

if found, the Field searched for; otherwise, null