⇒ Index (Frames) |  ⇒ Index (No Frames) |  ⇒ Package |  ⇒ Package Tree |  ⇒ Full Tree 
javax.mail

Interface Part

All Known Direct Subinterfaces:
MimePart


public interface Part

The Part interface is the common base interface for Messages and BodyParts.

Part consists of a set of attributes and a "Content".

Attributes:

The JavaMail API defines a set of standard Part attributes that are considered to be common to most existing Mail systems. These attributes have their own settor and gettor methods. Mail systems may support other Part attributes as well, these are represented as name-value pairs where both the name and value are Strings.

Content:

The data type of the "content" is returned by the getContentType() method. The MIME typing system is used to name data types.

The "content" of a Part is available in various formats:

Part provides the writeTo() method that streams out its bytestream in mail-safe form suitable for transmission. This bytestream is typically an aggregation of the Part attributes and its content's bytestream.

Message and BodyPart implement the Part interface. Note that in MIME parlance, Part models an Entity (RFC 2045, Section 2.4).

Author:

Method Summary

void

addHeader(String name, String value)

Add this value to the existing values for this header name.

Enumeration

getAllHeaders()

Return all the headers from this part as an Enumeration of Header objects.

Object

getContent()

Return the content as a Java object.

String

getContentType()

Returns the Content-Type of the content of this part.

DataHandler

getDataHandler()

Return a DataHandler for the content within this part.

String

getDescription()

Return a description String for this part.

String

getDisposition()

Return the disposition of this part.

String

getFileName()

Get the filename associated with this part, if possible.

String[]

getHeader(String name)

Get all the headers for this header name.

InputStream

getInputStream()

Return an input stream for this part's "content".

int

getLineCount()

Return the number of lines in the content of this part.

Enumeration

getMatchingHeaders(String[] names)

Return matching headers from this part as an Enumeration of Header objects.

Enumeration

getNonMatchingHeaders(String[] names)

Return non-matching headers from this envelope as an Enumeration of Header objects.

int

getSize()

Return the size of the content of this part in bytes.

boolean

isMimeType(String mimeType)

Is this Part of the specified MIME type? This method compares only the primaryType and subType.

void

removeHeader(String name)

Remove all headers with this name.

void

setContent(Object obj, String type)

A convenience method for setting this part's content.

void

setContent(Multipart mp)

This method sets the given Multipart object as this message's content.

void

setDataHandler(DataHandler dh)

This method provides the mechanism to set this part's content.

void

setDescription(String description)

Set a description String for this part.

void

setDisposition(String disposition)

Set the disposition of this part.

void

setFileName(String filename)

Set the filename associated with this part, if possible.

void

setHeader(String name, String value)

Set the value for this header name.

void

setText(String text)

A convenience method that sets the given String as this part's content with a MIME type of "text/plain".

void

writeTo(OutputStream os)

Output a bytestream for this Part.

Method Details

addHeader

public void addHeader(String name, String value)

Add this value to the existing values for this header name.

Parameters:
name - the name of this header
value - the value for this header
Throws:
IllegalWriteException - if the underlying implementation does not support modification of this header
- if this Part is obtained from a READ_ONLY folder

getAllHeaders

public Enumeration getAllHeaders()

Return all the headers from this part as an Enumeration of Header objects.


getContent

public Object getContent()

Return the content as a Java object. The type of the returned object is of course dependent on the content itself. For example, the object returned for "text/plain" content is usually a String object. The object returned for a "multipart" content is always a Multipart subclass. For content-types that are unknown to the DataHandler system, an input stream is returned as the content

This is a convenience method that just invokes the DataHandler's getContent() method

Throws:
- this is typically thrown by the DataHandler.

getContentType

public String getContentType()

Returns the Content-Type of the content of this part. Returns null if the Content-Type could not be determined.

The MIME typing system is used to name Content-types.


getDataHandler

public DataHandler getDataHandler()

Return a DataHandler for the content within this part. The DataHandler allows clients to operate on as well as retrieve the content.


getDescription

public String getDescription()

Return a description String for this part. This typically associates some descriptive information with this part. Returns null if none is available.


getDisposition

public String getDisposition()

Return the disposition of this part. The disposition describes how the part should be presented to the user. (See RFC 2183.) The return value should be considered without regard to case. For example:
String disp = part.getDisposition();
if (disp == null || disp.equalsIgnoreCase(Part.ATTACHMENT))
// treat as attachment if not first par


getFileName

public String getFileName()

Get the filename associated with this part, if possible. Useful if this part represents an "attachment" that was loaded from a file. The filename will usually be a simple name, not including directory components.


getHeader

public String[] getHeader(String name)

Get all the headers for this header name. Returns null if no headers for this header name are available.

Parameters:
name - the name of this header

getInputStream

public InputStream getInputStream()

Return an input stream for this part's "content". Any mail-specific transfer encodings will be decoded before the input stream is provided.

This is typically a convenience method that just invokes the DataHandler's getInputStream() method.

Throws:
- this is typically thrown by the DataHandler.

getLineCount

public int getLineCount()

Return the number of lines in the content of this part. Return -1 if the number cannot be determined. Note that this number may not be an exact measure of the content length and may or may not account for any transfer encoding of the content.


getMatchingHeaders

public Enumeration getMatchingHeaders(String[] names)

Return matching headers from this part as an Enumeration of Header objects.

Parameters:
names

getNonMatchingHeaders

public Enumeration getNonMatchingHeaders(String[] names)

Return non-matching headers from this envelope as an Enumeration of Header objects.

Parameters:
names

getSize

public int getSize()

Return the size of the content of this part in bytes. Return -1 if the size cannot be determined.

Note that the size may not be an exact measure of the content size and may or may not account for any transfer encoding of the content. The size is appropriate for display in a user interface to give the user a rough idea of the size of this part.


isMimeType

public boolean isMimeType(String mimeType)

Is this Part of the specified MIME type? This method compares only the primaryType and subType. The parameters of the content types are ignored.

For example, this method will return true when comparing a Part of content type "text/plain" with "text/plain; charset=foobar".

If the subType of mimeType is the special character '*', then the subtype is ignored during the comparison.

Parameters:
mimeType

removeHeader

public void removeHeader(String name)

Remove all headers with this name.

Parameters:
name - the name of this header
Throws:
IllegalWriteException - if the underlying implementation does not support modification of this header
- if this Part is obtained from a READ_ONLY folder

setContent

public void setContent(Object obj, String type)

A convenience method for setting this part's content. The part internally wraps the content in a DataHandler.

Note that a DataContentHandler class for the specified type should be available to the JavaMail implementation for this to work right. i.e., to do setContent(foobar, "application/x-foobar"), a DataContentHandler for "application/x-foobar" should be installed. Refer to the Java Activation Framework for more information.

Parameters:
obj - A java object.
type - MIME type of this object.
Throws:
IllegalWriteException - if the underlying implementation does not support modification of this header
- if this Part is obtained from a READ_ONLY folder

setContent

public void setContent(Multipart mp)

This method sets the given Multipart object as this message's content.

Parameters:
mp - The multipart object that is the Message's content
Throws:
IllegalWriteException - if the underlying implementation does not support modification of this header
- if this Part is obtained from a READ_ONLY folder

setDataHandler

public void setDataHandler(DataHandler dh)

This method provides the mechanism to set this part's content. The DataHandler wraps around the actual content.

Parameters:
dh - The DataHandler for the content.
Throws:
IllegalWriteException - if the underlying implementation does not support modification of this header
- if this Part is obtained from a READ_ONLY folder

setDescription

public void setDescription(String description)

Set a description String for this part. This typically associates some descriptive information with this part.

Parameters:
description - description of this part
Throws:
IllegalWriteException - if the underlying implementation does not support modification of this header
- if this Part is obtained from a READ_ONLY folder

setDisposition

public void setDisposition(String disposition)

Set the disposition of this part.

Parameters:
disposition - disposition of this part
Throws:
IllegalWriteException - if the underlying implementation does not support modification of this header
- if this Part is obtained from a READ_ONLY folder

setFileName

public void setFileName(String filename)

Set the filename associated with this part, if possible. Useful if this part represents an "attachment" that was loaded from a file. The filename will usually be a simple name, not including directory components.

Parameters:
filename - Filename to associate with this part
Throws:
IllegalWriteException - if the underlying implementation does not support modification of this header
- if this Part is obtained from a READ_ONLY folder

setHeader

public void setHeader(String name, String value)

Set the value for this header name. Replaces all existing header values with this new value.

Parameters:
name - the name of this header
value - the value for this header
Throws:
IllegalWriteException - if the underlying implementation does not support modification of this header
- if this Part is obtained from a READ_ONLY folder

setText

public void setText(String text)

A convenience method that sets the given String as this part's content with a MIME type of "text/plain".

Parameters:
text - The text that is the Message's content.
Throws:
IllegalWriteException - if the underlying implementation does not support modification of this header
- if this Part is obtained from a READ_ONLY folder

writeTo

public void writeTo(OutputStream os)

Output a bytestream for this Part. This bytestream is typically an aggregration of the Part attributes and an appropriately encoded bytestream from its 'content'.

Classes that implement the Part interface decide on the appropriate encoding algorithm to be used.

The bytestream is typically used for sending.

Parameters:
os
Throws:
- if an error occurs writing to the stream or if an error is generated by the javax.activation layer.
MessagingException - if an error occurs fetching the data to be written