com.hunnysoft.jmime
Class DispositionType

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

All Implemented Interfaces:

java.lang.Cloneable

public class DispositionType

extends FieldBody

Class that represents a MIME "Content-Disposition" field body.

DispositionType represents a field body for the content-disposition header field as described in RFC 2183. This header field specifies whether the content of a message or body part should be displayed automatically to a user. A disposition type of inline indicates that the content should be displayed; a disposition type of attachment indicates that it should not be. RFC 2183 specifies that a filename parameter may be optionally included in the field body; the filename parameter suggests a file name for saving the message or body part's content.

DispositionType provides methods that allow you to set or get the disposition type value and to manage a list of parameters. DispositionType also provides a convenience method that allows you to set or get the filename parameter.

Field Summary

static int	ATTACHMENT Enumerated value for attachment disposition type
static int	INLINE Enumerated value for inline disposition type
static int	NULL Enumerated value for unset disposition type
static int	UNKNOWN Enumerated value for unknown disposition type

Fields inherited from class com.hunnysoft.jmime.FieldBody

mText

Fields inherited from class com.hunnysoft.jmime.Node

mIsModified, mParent, mString

Constructor Summary

DispositionType()
Default constructor.

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

DispositionType(DispositionType other)
Copy constructor.

Method Summary

void	addParameter(Parameter param) Adds a parameter to the end of the list.
int	asEnum() Gets the disposition type as an enumerated value.
void	assemble() Assembles the string representation.
java.lang.Object	clone() Creates a copy of this object.
void	deleteAllParameters() Deletes all parameters in the list.
java.lang.String	filename() Gets the value of the filename parameter, if present.
java.lang.String	filenameU() Gets the decoded filename parameter, if present.
void	fromEnum(int type) Sets the disposition type from an enumerated value.
void	insertParameterAt(int index, Parameter param) Inserts a parameter at the specified position.
int	numParameters() Gets the number of parameters in the list.
Parameter	parameterAt(int index) Gets the parameter at the specified position.
void	parse() Parses the string representation.
Parameter	removeParameterAt(int index) Removes the parameter at the specified position.
void	setFilename(java.lang.String name) Sets the value of the filename parameter.
void	setFilenameU(java.lang.String name) Sets the encoded filename parameter.
void	setType(java.lang.String type) Sets the disposition type value.
java.lang.String	type() Gets the disposition type value.

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

Field Detail

NULL

public static final int NULL

Enumerated value for unset disposition type

See Also:

Constant Field Values

UNKNOWN

public static final int UNKNOWN

Enumerated value for unknown disposition type

See Also:

Constant Field Values

INLINE

public static final int INLINE

Enumerated value for inline disposition type

See Also:

Constant Field Values

ATTACHMENT

public static final int ATTACHMENT

Enumerated value for attachment disposition type

See Also:

Constant Field Values

Constructor Detail

DispositionType

public DispositionType()

Default constructor.

This constructor sets the DispositionType object's string representation to the empty string and sets its parent node to null. The list of Parameter objects is initially empty.

DispositionType

public DispositionType(DispositionType other)

Copy constructor.

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

Parameters:

other - DispositionType instance to copy

DispositionType

public DispositionType(ByteString bstr)

Constructor that takes an initial byte string argument.

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

Overrides:

clone in class FieldBody

Returns:

a copy of this object

type

public java.lang.String type()

Gets the disposition type value.

Returns:

disposition type value

setType

public void setType(java.lang.String type)

Sets the disposition type value.

Parameters:

type - disposition type value

asEnum

public int asEnum()

Gets the disposition type as an enumerated value.

Returns:

disposition type as an enumerated value

fromEnum

public void fromEnum(int type)

Sets the disposition type from an enumerated value.

Parameters:

type - disposition type as an enumerated value

filename

public java.lang.String filename()

Gets the value of the filename parameter, if present.

The filename parameter suggests a file name for the body part, which in most cases is a file attachment.

This convenience method gets the value of the filename parameter, if it is present. If it is absent, then this method returns an empty string.

The filename method gets the value of only the unencoded filename parameter. In most cases, you should use the filenameU() method, which gets the decoded value of the encoded filename parameter.

Returns:

value of the filename parameter; or the empty string if there is no filename parameter

setFilename

public void setFilename(java.lang.String name)

Sets the value of the filename parameter.

The filename parameter suggests a file name for the body part, which in most cases is a file attachment.

This convenience method sets the value of the filename parameter to name.

To comply with RFC 2822 and MIME, the file name must contain only ASCII characters. Hunny JMIME also provides a setFilenameU(java.lang.String) convenience method that accepts any Unicode file name and correctly encodes it according to the MIME standard.

Parameters:

name - value of the filename parameter

See Also:

filename(), setFilenameU(java.lang.String)

filenameU

public java.lang.String filenameU()

Gets the decoded filename parameter, if present.

The filename parameter suggests a file name for the body part, which in most cases is a file attachment.

RFC 2231 specifies how parameters in a MIME header field should be encoded if they contain values with non-ASCII characters, or if they have values that are too long to fit on a single line. Hunny JMIME provides the filenameU convenience method to decode a filename parameter that is encoded according to RFC 2231.

Not many email clients support RFC 2231. Notably, Microsoft Outlook does not support it. Mozilla Thunderbird can accept a filename parameter encoded according to RFC 2231; however, it does not generate RFC-2231-encoded filename parameters. Therefore, it is probably a good idea to include both an unencoded filename and an encoded filename parameter. The following example has an unencoded and an encoded filename parameter:

 Disposition-Type: attachment;
   filename="Viel Spass.txt";
   filename*=utf-8''Viel%20Spa%c3%9f
 

Hunny JMIME provides the filename() convenience method to get the unencoded filename parameter. However, that method is not really necessary. If you want to keep your code simple, you can use just the filenameU method. filenameU gets the encoded filename parameter (filename*) if it's present, but gets the unencoded parameter (filename) if the encoded filename parameter is absent.

Returns:

the Unicode file name, if present; otherwise, an empty string

See Also:

RFC 2231 MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations

setFilenameU

public void setFilenameU(java.lang.String name)

Sets the encoded filename parameter.

The filename parameter suggests a file name for the body part, which in most cases is a file attachment.

RFC 2231 specifies how parameters in a MIME header field should be encoded if they contain values with non-ASCII characters, or if they have values that are too long to fit on a single line. Hunny JMIME provides the setFilenameU convenience method to encode the filename parameter according to RFC 2231.

The setFilenameU method encodes to UTF-8 only. The rationale for this decision is that all modern operating systems use Unicode for file names. So, if you encode a file name from Unicode into, say, EUC-KR (Korean), then the receiving implementation must decode from EUC-KR back into Unicode in order to pass the file name to the operating system.

Not many email clients support RFC 2231. Notably, Microsoft Outlook does not support it. Mozilla Thunderbird can accept a filename parameter encoded according to RFC 2231; however, it does not generate RFC-2231-encoded filename parameters. Therefore, it is probably a good idea to include both an unencoded filename and an encoded filename parameter. The following example has an unencoded and an encoded filename parameter:

 Disposition-Type: attachment;
   filename="Viel Spass.txt";
   filename*=utf-8''Viel%20Spa%c3%9f
 

With Hunny JMIME, you can set both an unencoded filename parameter and an encoded filename parameter. Use the setFilename(java.lang.String) method to set the unencoded filename parameter. Use setFilenameU to set the encoded filename parameter.

Parameters:

name - the value for the encoded filename parameter

See Also:

RFC 2231 MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations

parse

public void parse()

Parses the string representation.

This method, inherited from Node, executes the parse operation for DispositionType objects. The parse operation creates or updates the broken-down representation from the string representation. For DispositionType objects, the parse operation parses the string representation to extract the disposition type value and the list of Parameter objects. This method also calls the parse() method of each Parameter object in its list.

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

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 DispositionType objects. The assemble operation creates or updates the string representation from the broken-down representation. For DispositionType objects, the assemble operation builds the string representation from the disposition type value and the list of Parameter objects. Before it builds the string representation for the DispositionType object, this method first calls the assemble() method of each Parameter object in its list.

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

This method clears the is-modified flag.

Overrides:

assemble in class FieldBody

numParameters

public int numParameters()

Gets the number of parameters in the list.

Returns:

number of parameters in the list

addParameter

public void addParameter(Parameter param)

Adds a parameter to the end of the list.

Parameters:

param - Parameter object to add

deleteAllParameters

public void deleteAllParameters()

Deletes all parameters in the list.

parameterAt

public Parameter parameterAt(int index)

Gets the parameter at the specified position.

Parameters:

index - position of the Parameter object to get (0 <= index < numParameters())

Returns:

Parameter object at the specified position

Throws:

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

insertParameterAt

public void insertParameterAt(int index,
                              Parameter param)

Inserts a parameter at the specified position.

Inserting at position 0 inserts the parameter at the beginning. Inserting at position numParameters() appends the parameter to the end.

Parameters:

index - position in the list to insert the Parameter object (0 <= index <= numParameters())

param - Parameter object to insert

Throws:

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

removeParameterAt

public Parameter removeParameterAt(int index)

Removes the parameter at the specified position.

Parameters:

index - position of the Parameter object to remove (0 <= index < numParameters())

Returns:

the removed Parameter object

Throws:

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