Node Class Reference

Abstract base class for all classes representing message components. More...

Inheritance diagram for Node:

List of all members.

Public Member Functions
	Node ()
	Default constructor.
	Node (const Node &other)
	Copy constructor.
	Node (const String &str, Node *parent=0)
	Constructor that takes an initial string and parent node.
virtual	~Node ()
	Destructor.
const Node &	operator= (const Node &other)
	Assignment operator.
virtual void	parse ()=0
	Parses the string representation.
virtual void	assemble ()=0
	Assembles the string representation.
virtual Node *	clone () const =0
	Creates a copy of this object.
void	setString (const String &str)
	Sets the string representation.
void	setString (const char *cstr)
	Sets the string representation.
const String &	getString () const
	Gets the string representation.
Node *	parent () const
	Gets the parent node.
void	setParent (Node *parent)
	Sets the parent node.
bool	isModified () const
	Gets the is-modified flag.
void	setModified ()
	Sets the is-modified flag.
class Class &	class_ () const
	Gets a reference to the singleton Class instance.
void	_setString (const String &str)
	Sets the string representation.
Protected Attributes
String	mString
	String representation
bool	mIsModified
	Is-modified flag.
Node *	mParent
	Parent node.
class Class *	mClass
	Pointer to the singleton Class instance.

---

Detailed Description

Node is the root of an inheritance hierarchy that includes many classes in Hunny MIME++. All classes that represent MIME document components are subclasses of Node. The Node class defines important features that are inherited by these subclasses. These features are the following:

• A string representation. The string representation is the serialized representation of a MIME document component. The Node class provides a member function setString() to set the string representation and a member function getString() to get the string representation.

• A broken-down representation. The broken-down representation is the parsed representation of a MIME document component. For example, the broken-down representation of an RFC 2822 date-time consists of the year, month, day, hour, minute, second, and time zone. Subclasses of Node provide member functions to set or get elements of the broken-down representation.

• A parse operation to create or update the broken-down representation from the string representation. In the DateTime class, for example, the parse operation parses the year, month, day, hour, minute, second, and time zone from the RFC 2822 date-time string contained in the string representation. Node provides a pure virtual function parse() that subclasses override to execute the parse operation.

• An assemble operation to create or update the string representation from the broken-down representation. This is the opposite of the parse operation. In the DateTime class, for example, the assemble operation creates an RFC 2822 date-time string from values of the year, month, day, hour, minute, second, and time zone. Node provides a pure virtual function assemble() that subclasses override to execute the assemble operation.

• An is-modified flag. When the string representation and the broken-down representation are consistent, the assemble operation does not need to be executed. The is-modified flag indicates if the string representation and the broken-down representation are consistent. The flag is cleared when the two representations are consistent, and is set when they are inconsistent. The flag is set when a Node object's broken-down representation is changed by calling one of its member functions. It is cleared when the assemble or parse operation is executed. Node also provides a member function setModified() that sets the is-modified flag.

  Normally, you can ignore the is-modified flag. The assemble() function always checks the is-modified flag and returns immediately if the flag is cleared. The library uses the is-modified flag to optimize the assemble() function.

• A parent node. Hunny MIME++ maintains a tree structure of Node objects. The parent-child relationship among Node objects parallels the superstring-substring relationship among the "components" of a MIME document. For example, where a MIME message contains substrings for the headers and the body, Hunny MIME++ provides a Message node object that has a Headers child node and a Body child node. Where a MIME headers string contains a substring for each header field, Hunny MIME++ provides a Headers node object that has a collection of Field child nodes.

  To maintain consistency in the tree, whenever a node's is-modified flag is set, the node requests its parent to also set its is-modified flag. In this way, an is-modified flag set anywhere in the tree always propagates to the root node.

• Child nodes. Subclasses of Node provide member functions to access their child nodes. A node's parse operation invokes the parse operations of its child nodes after it has updated its broken-down representation. Also, a node's assemble operation invokes the assemble operations of its child nodes before it updates its string representation.

---

Constructor & Destructor Documentation

Node

(

)

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

Node

(

const Node &

other

)

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

Parameters:

other

Node instance to copy

Node	(	const String &	str,
		Node *	parent = 0
	)

This constructor sets the Node object's string representation to str and sets its parent node to parent.

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

Parameters:

	str	initial value for the string representation
	parent	parent node for this object

~Node

(

)

[virtual]

Destructor

---

Member Function Documentation

void _setString

(

const String &

str

)

Sets the string representation.

This is an advanced function that the library itself uses. It is public so that developers may extend the library. Unlike setString(), this function does not set the is-modified flag of the parent node.

Parameters:

str

new value for the string representation

See also:

setString()

void assemble

(

)

[pure virtual]

This pure virtual function executes the assemble operation. The assemble operation creates or updates the string representation from the broken-down representation. The assemble operation is the opposite of the parse operation. Before creating or updating the string representation, the assemble operation invokes the assemble operation of each of its child nodes. If the is-modifed flag for a Node is cleared, the assemble() function will return immediately without calling the assemble() function of any of its child nodes, and without updating the string representation.

This function clears the is-modified flag.

See also:

parse().

Implemented in Parameter, FieldBody, MsgId, EncodedWord, Text, Mailbox, AddressList, MailboxList, Group, DateTime, DispositionType, Stamp, TransferEncodingType, MediaType, Field, Headers, Body, and Entity.

class Class & class_

(

)

const

Gets a reference to the singleton Class instance.

The Class class provides run-time type information about objects in Hunny MIME++.

Returns:

singleton Class instance

Node * clone

(

)

const [pure virtual]

Creates a new object that has the same type and value as this object.

Returns:

a clone of this object

Implemented in Parameter, FieldBody, MsgId, EncodedWord, Text, Mailbox, AddressList, MailboxList, Group, DateTime, DispositionType, Stamp, TransferEncodingType, MediaType, Field, Headers, Body, BodyPart, and Message.

const String & getString

(

)

const

Gets the string representation.

If the broken-down representation and the string representation are not consistent, you should call the assemble() member function before you call getString(), so that the string representation will be updated first.

Returns:

the string representation

See also:

assemble().

bool isModified

(

)

const

Returns true if the is-modified flag is set.

Returns:

true if the is-modified flag is set

const Node & operator=

(

const Node &

other

)

Performs a deep copy of its argument. The parent node is not changed.

Parameters:

other

instance to copy

Node * parent

(

)

const

Gets the parent node.

Returns:

the parent node

void parse

(

)

[pure virtual]

This virtual function executes the parse operation. The parse operation creates or updates the broken-down representation from the string representation. The parse operation is the opposite of the assemble operation. In some derived classes, such as Headers, the parse operation also creates the child nodes of the object. (In the case of Headers, the child nodes are Field objects that represent the header fields contained in the headers.) The parse() member function calls the parse() member functions of all the object's child nodes.

This function clears the is-modified flag.

See also:

assemble().

Implemented in Parameter, FieldBody, MsgId, EncodedWord, Text, Mailbox, AddressList, MailboxList, Group, DateTime, DispositionType, Stamp, TransferEncodingType, MediaType, Field, Headers, Body, and Entity.

void setModified

(

)

Sets the is-modified flag and requests the parent node to set its is-modified flag.

void setParent

(

Node *

parent

)

Sets the parent node.

Parameters:

parent

the parent node

void setString

(

const char *

cstr

)

Sets the string representation.

cstr must be NUL-terminated.

Normally, you call the virtual function parse() immediately after this function to update the broken-down representation.

Parameters:

cstr

new value for the string representation

See also:

parse()

void setString

(

const String &

str

)

Sets the string representation.

Normally, you call the virtual function parse() immediately after this function to update the broken-down representation.

Parameters:

str

new value for the string representation

See also:

parse()