com.hunnysoft.jmime
Class Stamp

java.lang.Object
  com.hunnysoft.jmime.Node
      com.hunnysoft.jmime.FieldBody
          com.hunnysoft.jmime.Stamp

All Implemented Interfaces:

java.lang.Cloneable

public class Stamp

extends FieldBody

Class that represents the field body of a "Received" header field.

Stamp represents a field body for the "Received" header field as described in RFC 2821 and RFC 2822. (RFC 2821 uses the term time stamp to describe the contents of the "Received" header field.) One "Received" header field is normally added by every host that relays a message through the transport system, as required by SMTP. The field includes a time stamp indicating the time that the message was received at the host, and possibly other information.

The "Received" header field provides information that may be helpful in resolving mail delivery problems. In practice, though, the most recent time stamp is often used by email client applications to obtain the time that the message was received by that client's mail server. The other information provided in the "Received" header field is optional and inconsistent between implementations. Some implementations do not provide much of the optional information, while other implementations provide it in non-standard forms.

The following is a sample time stamp line, which shows all the optional information:

    Received: from xyz.net by mx.org via TELENET with SMTP
        id M12345 for smith@aol.com ; Tue, 6 Oct 1998 09:23:59 -0700

Stamp provides access to all the information provided in a "Received" header field body, including sending host ("xyz.net"), receiving host ("mx.org"), physical mechanism ("TELENET"), protocol ("SMTP"), internal message identifier ("M12345"), original addressee ("smith@aol.com"), and date/time the message was received ("Tue, 6 Oct 1998 09:23:59 -0700"). If an optional field is not present, then the "getter" method for that field returns an empty string.

Stamp follows the protocol for parse() and assemble() as required by Node.

Note: Because of inconsistencies in many server implementations, the parsing may not be reliable enough for applications to depend on. The only parsed information that you should probably rely on is the final date/time stamp. RFC 2821 suggests that the "Received" header field is intended mostly for inspection by mail system administrators to resolve mail delivery problems.

Field Summary

Fields inherited from class com.hunnysoft.jmime.FieldBody

mText

Fields inherited from class com.hunnysoft.jmime.Node

mIsModified, mParent, mString

Constructor Summary

Stamp()
Default constructor.

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

Stamp(Stamp other)
Copy constructor.

Method Summary

void	assemble() Assembles the string representation.
java.lang.String	by() Gets the receiving host.
java.lang.Object	clone() Creates a copy of this object.
DateTime	date() Gets the date and time that the message was received.
java.lang.String	for_() Gets the original addressee.
java.lang.String	from() Gets the sending host.
java.lang.String	id() Gets the internal message identifier.
void	parse() Parses the string representation.
void	setBy(java.lang.String receivingHost) Sets the receiving host.
void	setDate(DateTime date) Sets the date and time that the message was received.
void	setFor(java.lang.String addressee) Sets the original addressee.
void	setFrom(java.lang.String sendingHost) Sets the sending host.
void	setId(java.lang.String id) Sets the internal message identifier.
void	setVia(java.lang.String mechanism) Sets the physical mechanism.
void	setWith(java.lang.String protocol) Sets the protocol.
java.lang.String	via() Gets the physical mechanism through which the message was received.
java.lang.String	with() Gets the protocol that was used to send this message.

Methods inherited from class com.hunnysoft.jmime.FieldBody

fold, isFoldingEnabled, maybeFold, setFoldingEnabled, setText, text, unfold

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

Constructor Detail

Stamp

public Stamp()

Default constructor.

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

Stamp

public Stamp(Stamp other)

Copy constructor.

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

Parameters:

other - Stamp instance to copy

Stamp

public Stamp(ByteString bstr)

Constructor that takes an initial byte string argument.

This constructor sets the Stamp 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 Stamp object that has the same value as this Stamp object. The parent node of the new Stamp object is set to null.

Overrides:

clone in class FieldBody

Returns:

a copy of this object

parse

public void parse()

Parses the string representation.

This method, inherited from Node, executes the parse operation for Stamp objects. The parse operation creates or updates the broken-down representation from the string representation. For Stamp objects, the parse operation parses the string representation to extract the from, by, via, with, id, for, and date attributes. This method also calls the parse() method of its contained DateTime object.

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

This method clears the is-modified flag.

Overrides:

parse in class FieldBody

assemble

public void assemble()

Assembles the string representation.

This method, inherited from Node, executes the assemble operation for Stamp objects. The assemble operation creates or updates the string representation from the broken-down representation. For Stamp objects, the assemble operation builds the string representation from the Stamp object's attributes. Before it builds the string representation, this method first calls the assemble() method of the object's contained DateTime object.

You should call this method after you set or modify any of the attributes of this Stamp object, and before you retrieve the string representation.

This method clears the is-modified flag.

Overrides:

assemble in class FieldBody

from

public java.lang.String from()

Gets the sending host.

In the "Received" header field, the sending host follows the "from" keyword. If the sending host is not present, this method returns an empty string.

Returns:

the sending host

setFrom

public void setFrom(java.lang.String sendingHost)

Sets the sending host.

Parameters:

sendingHost - the sending host

by

public java.lang.String by()

Gets the receiving host.

The receiving host is the host that added this field to the message headers. In the "Received" header field, the receiving host follows the "by" keyword. If the receiving host is not present, this method returns an empty string.

Returns:

the receiving host

setBy

public void setBy(java.lang.String receivingHost)

Sets the receiving host.

Parameters:

receivingHost - the receiving host

via

public java.lang.String via()

Gets the physical mechanism through which the message was received.

In the "Received" header field, the physical mechanism follows the "via" keyword. If the physical mechanism is not present, this method returns an empty string.

Returns:

the physical mechanism

setVia

public void setVia(java.lang.String mechanism)

Sets the physical mechanism.

Parameters:

mechanism - the physical mechanism

with

public java.lang.String with()

Gets the protocol that was used to send this message.

In the "Received" header field, the protocol follows the "with" keyword. Usually, the protocol is SMTP or ESMTP. If the protocol is not present, this method returns an empty string.

Returns:

the protocol

setWith

public void setWith(java.lang.String protocol)

Sets the protocol.

Parameters:

protocol - the protocol

id

public java.lang.String id()

Gets the internal message identifier.

This is a value that is meaningful to the receiving host, such as the name of a file that was used to temporarily store the message. In the "Received" header field, the identifier follows the "id" keyword. If the identifier is not present, this method returns an empty string.

Returns:

identifier

setId

public void setId(java.lang.String id)

Sets the internal message identifier.

Parameters:

id - identifier

for_

public java.lang.String for_()

Gets the original addressee.

This information may be important if some kind of address translation occurs. In the "Received" header field, the addressee follows the "for" keyword. If the original addressee is not present, this method returns an empty string.

Returns:

addressee

setFor

public void setFor(java.lang.String addressee)

Sets the original addressee.

Parameters:

addressee - the addressee

date

public DateTime date()

Gets the date and time that the message was received.

This information is the only required information in the "Received" header field.

Returns:

date and time the message was received

setDate

public void setDate(DateTime date)

Sets the date and time that the message was received.

Parameters:

date - date and time the message was received