Interface Part
-
- All Known Subinterfaces:
MimePart
- All Known Implementing Classes:
BodyPart
,Message
,MimeBodyPart
,MimeMessage
,PreencodedMimeBodyPart
public interface Part
ThePart
interface is the common base interface for Messages and BodyParts.Part consists of a set of attributes and a "Content".
Attributes:
The Jakarta Mail 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:
- As a DataHandler - using the
getDataHandler()
method. The "content" of a Part is also available through ajakarta.activation.DataHandler
object. The DataHandler object allows clients to discover the operations available on the content, and to instantiate the appropriate component to perform those operations. - As an input stream - using the
getInputStream()
method. Any mail-specific encodings are decoded before this stream is returned. - As a Java object - using the
getContent()
method. This method returns the "content" as a Java object. The returned object is of course dependent on the content itself. In particular, a "multipart" Part's content is always a Multipart or subclass thereof. That is,getContent()
on a "multipart" type Part will always return a Multipart (or subclass) object.
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:
- John Mani
-
-
Field Summary
Fields Modifier and Type Field Description static String
ATTACHMENT
This part should be presented as an attachment.static String
INLINE
This part should be presented inline.
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addHeader(String header_name, String header_value)
Add this value to the existing values for this header_name.Enumeration<Header>
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 header_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<Header>
getMatchingHeaders(String[] header_names)
Return matching headers from this part as an Enumeration of Header objects.Enumeration<Header>
getNonMatchingHeaders(String[] header_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 theprimaryType
andsubType
.void
removeHeader(String header_name)
Remove all headers with this name.void
setContent(Multipart mp)
This method sets the given Multipart object as this message's content.void
setContent(Object obj, String type)
A convenience method for setting this part'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 header_name, String header_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 Detail
-
getSize
int getSize() throws MessagingException
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.
- Returns:
- size of content in bytes
- Throws:
MessagingException
- for failures
-
getLineCount
int getLineCount() throws MessagingException
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.- Returns:
- number of lines in the content.
- Throws:
MessagingException
- for failures
-
getContentType
String getContentType() throws MessagingException
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.
- Returns:
- The ContentType of this part
- Throws:
MessagingException
- for failures- See Also:
DataHandler
-
isMimeType
boolean isMimeType(String mimeType) throws MessagingException
Is this Part of the specified MIME type? This method compares only theprimaryType
andsubType
. 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
ofmimeType
is the special character '*', then the subtype is ignored during the comparison.- Parameters:
mimeType
- the MIME type to test- Returns:
- true if this part is of the specified type
- Throws:
MessagingException
- for failures
-
getDisposition
String getDisposition() throws MessagingException
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 part
- Returns:
- disposition of this part, or null if unknown
- Throws:
MessagingException
- for failures- See Also:
ATTACHMENT
,INLINE
,getFileName()
-
setDisposition
void setDisposition(String disposition) throws MessagingException
Set the disposition of this part.- Parameters:
disposition
- disposition of this part- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of this headerIllegalStateException
- if this Part is obtained from a READ_ONLY folderMessagingException
- for other failures- See Also:
ATTACHMENT
,INLINE
,setFileName(java.lang.String)
-
getDescription
String getDescription() throws MessagingException
Return a description String for this part. This typically associates some descriptive information with this part. Returns null if none is available.- Returns:
- description of this part
- Throws:
MessagingException
- for failures
-
setDescription
void setDescription(String description) throws MessagingException
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 headerIllegalStateException
- if this Part is obtained from a READ_ONLY folderMessagingException
- for other failures
-
getFileName
String getFileName() throws MessagingException
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.- Returns:
- Filename to associate with this part
- Throws:
MessagingException
- for failures
-
setFileName
void setFileName(String filename) throws MessagingException
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 headerIllegalStateException
- if this Part is obtained from a READ_ONLY folderMessagingException
- for other failures
-
getInputStream
InputStream getInputStream() throws IOException, MessagingException
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.- Returns:
- an InputStream
- Throws:
IOException
- this is typically thrown by the DataHandler. Refer to the documentation for jakarta.activation.DataHandler for more details.MessagingException
- for other failures- See Also:
getDataHandler()
,DataHandler.getInputStream()
-
getDataHandler
DataHandler getDataHandler() throws MessagingException
Return a DataHandler for the content within this part. The DataHandler allows clients to operate on as well as retrieve the content.- Returns:
- DataHandler for the content
- Throws:
MessagingException
- for failures
-
getContent
Object getContent() throws IOException, MessagingException
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 contentThis is a convenience method that just invokes the DataHandler's getContent() method
- Returns:
- Object
- Throws:
IOException
- this is typically thrown by the DataHandler. Refer to the documentation for jakarta.activation.DataHandler for more details.MessagingException
- for other failures- See Also:
DataHandler.getContent()
-
setDataHandler
void setDataHandler(DataHandler dh) throws MessagingException
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 existing valuesIllegalStateException
- if this Part is obtained from a READ_ONLY folderMessagingException
- for other failures
-
setContent
void setContent(Object obj, String type) throws MessagingException
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 Jakarta Mail 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 existing valuesIllegalStateException
- if this Part is obtained from a READ_ONLY folderMessagingException
- for other failures
-
setText
void setText(String text) throws MessagingException
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 existing valuesIllegalStateException
- if this Part is obtained from a READ_ONLY folderMessagingException
- for other failures
-
setContent
void setContent(Multipart mp) throws MessagingException
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 existing valuesIllegalStateException
- if this Part is obtained from a READ_ONLY folderMessagingException
- for other failures
-
writeTo
void writeTo(OutputStream os) throws IOException, MessagingException
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
- the stream to write to- Throws:
IOException
- if an error occurs writing to the stream or if an error is generated by the jakarta.activation layer.MessagingException
- if an error occurs fetching the data to be written- See Also:
DataHandler.writeTo(java.io.OutputStream)
-
getHeader
String[] getHeader(String header_name) throws MessagingException
Get all the headers for this header name. Returnsnull
if no headers for this header name are available.- Parameters:
header_name
- the name of this header- Returns:
- the value fields for all headers with this name
- Throws:
MessagingException
- for failures
-
setHeader
void setHeader(String header_name, String header_value) throws MessagingException
Set the value for this header_name. Replaces all existing header values with this new value.- Parameters:
header_name
- the name of this headerheader_value
- the value for this header- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesIllegalStateException
- if this Part is obtained from a READ_ONLY folderMessagingException
- for other failures
-
addHeader
void addHeader(String header_name, String header_value) throws MessagingException
Add this value to the existing values for this header_name.- Parameters:
header_name
- the name of this headerheader_value
- the value for this header- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesIllegalStateException
- if this Part is obtained from a READ_ONLY folderMessagingException
- for other failures
-
removeHeader
void removeHeader(String header_name) throws MessagingException
Remove all headers with this name.- Parameters:
header_name
- the name of this header- Throws:
IllegalWriteException
- if the underlying implementation does not support modification of existing valuesIllegalStateException
- if this Part is obtained from a READ_ONLY folderMessagingException
- for other failures
-
getAllHeaders
Enumeration<Header> getAllHeaders() throws MessagingException
Return all the headers from this part as an Enumeration of Header objects.- Returns:
- enumeration of Header objects
- Throws:
MessagingException
- for failures
-
getMatchingHeaders
Enumeration<Header> getMatchingHeaders(String[] header_names) throws MessagingException
Return matching headers from this part as an Enumeration of Header objects.- Parameters:
header_names
- the headers to match- Returns:
- enumeration of Header objects
- Throws:
MessagingException
- for failures
-
getNonMatchingHeaders
Enumeration<Header> getNonMatchingHeaders(String[] header_names) throws MessagingException
Return non-matching headers from this envelope as an Enumeration of Header objects.- Parameters:
header_names
- the headers to not match- Returns:
- enumeration of Header objects
- Throws:
MessagingException
- for failures
-
-