com.hunnysoft.jmime
Class Node

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

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

Body, EncodedWord, Entity, Field, FieldBody, Headers, Parameter

public abstract class Node

extends java.lang.Object

implements java.lang.Cloneable

Abstract base class for all classes representing message components.

Node is the root of an inheritance hierarchy that includes many classes in Hunny JMIME. 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 method setString(com.hunnysoft.jmime.ByteString) to set the string representation and a method string() 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 an abstract method 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 an abstract method 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 methods. It is cleared when the assemble or parse operation is executed. Node also provides a method setModified() that sets the is-modified flag.

  Normally, you can ignore the is-modified flag. The assemble() method 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() method.

• A parent node. Hunny JMIME 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, JMIME 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, JMIME 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 methods 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.

Field Summary

protected boolean	mIsModified Is-modified flag.
protected Node	mParent Parent node.
protected ByteString	mString String representation.

Constructor Summary

Node()
Default constructor.

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

Node(Node other)
Copy constructor.

Method Summary

void	_setString(ByteString bstr) Sets the string representation.
abstract void	assemble() Assembles the string representation.
java.lang.Object	clone() Throws UnsupportedOperationException.
boolean	isModified() Returns true if the is-modified flag is set.
Node	parent() Gets the parent node.
abstract void	parse() Parses the string representation.
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.
void	setString(ByteString bstr) Sets the string representation.
ByteString	string() Gets the string representation.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

mString

protected ByteString mString

String representation.

mParent

protected Node mParent

Parent node.

mIsModified

protected boolean mIsModified

Is-modified flag.

Constructor Detail

Node

public Node()

Default constructor.

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

Node

public Node(Node other)

Copy constructor.

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

public Node(ByteString bstr)

Constructor that takes an initial byte string argument.

This constructor sets the Node object's string representation to bstr. 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()

Throws UnsupportedOperationException.

Subclasses of Node override this function to return a copy of the object. Because Node is an abstract class, this method throws an UnsupportedOperationException.

Throws:

java.lang.UnsupportedOperationException

parse

public abstract void parse()

Parses the string representation.

This method 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() method calls the parse() method of all of the child nodes.

This function clears the is-modified flag.

See Also:

assemble()

assemble

public abstract void assemble()

Assembles the string representation.

This method 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() method will return immediately without calling the assemble() method of any of its child nodes, and without updating the string representation.

This function clears the is-modified flag.

See Also:

parse()

string

public final ByteString string()

Gets the string representation.

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

Returns:

the string representation

See Also:

assemble()

setString

public final void setString(ByteString bstr)

Sets the string representation.

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

Parameters:

bstr - new value for the string representation

See Also:

parse()

_setString

public final void _setString(ByteString bstr)

Sets the string representation.

This is an advanced method 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:

bstr - new value for the string representation

See Also:

setString(com.hunnysoft.jmime.ByteString)

parent

public final Node parent()

Gets the parent node.

Returns:

the parent node

setParent

public final void setParent(Node parent)

Sets the parent node.

Parameters:

parent - the parent node

isModified

public final boolean isModified()

Returns true if the is-modified flag is set.

Returns:

true if the is-modified flag is set

setModified

public final void setModified()

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

toString

public java.lang.String toString()