Package com.sun.mail.imap

# Class IMAPMessage

java.lang.Object
javax.mail.Message
javax.mail.internet.MimeMessage
com.sun.mail.imap.IMAPMessage

All Implemented Interfaces:
  `ReadableMime`, `MimePart`, `Part`

Direct Known Subclasses:
  `GmailMessage`, `IMAPNestedMessage`

public class IMAPMessage extends MimeMessage implements ReadableMime
This class implements an IMAPMessage object.

An IMAPMessage object starts out as a light-weight object. It gets filled-in incrementally when a request is made for some item. Or when a prefetch is done using the FetchProfile.

An IMAPMessage has a messageNumber and a sequenceNumber. The messageNumber is its index into its containing folder's messageCache. The sequenceNumber is its IMAP sequence-number.

Author:
  John Mani, Bill Shannon

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`IMAPMessage.FetchProfileCondition`
This class implements the test to be done on each message in the folder.

## Nested classes/interfaces inherited from class javax.mail.internet.MimeMessage

`MimeMessage.RecipientType`

## Field Summary

Fields
Modifier and Type
Field
Description
`protected BODYSTRUCTURE`
`bs`
`protected ENVELOPE`
`envelope`
`protected Map<String,Object>`
`items`
A map of the extension FETCH items.
`protected String`
`sectionId`

### Fields inherited from class javax.mail.internet.MimeMessage

`cachedContent, content, contentStream, dh, flags, headers, modified, saved`

### Fields inherited from class javax.mail.Message

`expunged, folder, msgnum, session`

### Fields inherited from interface javax.mail.Part

`ATTACHMENT, INLINE`

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`IMAPMessage(IMAPFolder folder, int msgnum)`
Constructor.
`protected`
`IMAPMessage(Session session)`
Constructor, for use by IMAPNestedMessage.

## Method Summary

Modifier and Type
Method
Description
`void`
`addFrom(Address[] addresses)`
Add the specified addresses to the existing "From" field.
`void`
`addHeader(String name, String value)`
Add this value to the existing values for this header_name.
`void`
`addHeaderLine(String line)`
Add a raw RFC 822 header-line.
`void`
`addRecipients(Message.RecipientType type, Address[] addresses)`
Add the given addresses to the specified recipient type.
`protected void`
`checkExpunged()`
`protected Object`
`fetchItem(FetchItem fitem)`
Fetch an individual item for the current message.
`protected void`
`forceCheckExpunged()`
Do a NOOP to force any untagged EXPUNGE responses and then check if this message is expunged.
`Enumeration<String>`
`getAllHeaderLines()`
Get all header-lines.
`Enumeration<Header>`
`getAllHeaders()`
Get all headers.
`String`
`getContentID()`
Get the Content-ID.
`String[]`
`getContentLanguage()`
Get the content language.
`String`
`getContentMD5()`
Get the Content-MD5.
`protected InputStream`
`getContentStream()`
Get all the bytes for this message.
`String`
`getContentType()`
Get the Content-Type.
`DataHandler`
`getDataHandler()`
Get the DataHandler object for this message.
`String`
`getDescription()`
Get the decoded Content-Description.
`String`
`getDisposition()`
Get the Content-Disposition.
`String`
`getEncoding()`
Get the Content-Transfer-Encoding.
`protected int`
`getFetchBlockSize()`
`String`
`getFileName()`
Get the "filename" Disposition parameter.
`Flags`
`getFlags()`
Get the Flags for this message.
`Address[]`
`getFrom()`
Get the "From" attribute.
`String[]`
`getHeader(String name)`
Get the named header.
`String`
`getHeader(String name, String delimiter)`
Get the named header.
`String`
`getInReplyTo()`
Get the In-Reply-To header.
`Object`
`getItem(FetchItem fitem)`
Return the data associated with the FetchItem.
`int`
`getLineCount()`
Get the total number of lines.
`Enumeration<String>`
`getMatchingHeaderLines(String[] names)`
Get all matching header-lines.
`Enumeration<Header>`
`getMatchingHeaders(String[] names)`
Get matching headers.
`protected Object`
`getMessageCacheLock()`
Get the messageCacheLock, associated with this Message's Folder.
`String`
`getMessageID()`
Get the Message-ID.
`InputStream`
`getMimeStream()`
Return the MIME format stream corresponding to this message.
`long`
`getModSeq()`
Return the modification sequence number (MODSEQ) for this message.
`Enumeration<String>`
`getNonMatchingHeaderLines(String[] names)`
Get all non-matching headerlines.
`Enumeration<Header>`
`getNonMatchingHeaders(String[] names)`
Get non-matching headers.
`boolean`
`getPeek()`
Get whether or not to use the PEEK variant of FETCH when fetching message content.
`protected IMAPProtocol`
`getProtocol()`
Get this message's folder's protocol connection.
`Date`
`getReceivedDate()`
Get the received date (INTERNALDATE).
`Address[]`
`getRecipients(Message.RecipientType type)`
Get the desired Recipient type.
`Address[]`
`getReplyTo()`
Get the ReplyTo addresses.
`Address`
`getSender()`
Get the "Sender" attribute.
`Date`
`getSentDate()`
Get the SentDate.
`protected int`
`getSequenceNumber()`
Get this message's IMAP sequence number.
`int`
`getSize()`
Get the message size.
`long`
`getSizeLong()`
Get the message size as a long.
`String`
`getSubject()`
Get the decoded subject.
`protected long`
`getUID()`
Return the UID for this message.
`protected void`
`handleExtensionFetchItems(Map<String,Object> extensionItems)`
Apply the data in the extension FETCH items to this message.
`protected boolean`
`handleFetchItem(Item item, String[] hdrs, boolean allHeaders)`
Apply the data in the FETCH item to this message.
`protected boolean`
`ignoreBodyStructureSize()`
`void`
`invalidateHeaders()`
Invalidate cached header and envelope information for this message.
`protected boolean`
`isREV1()`
`boolean`
`isSet(Flags.Flag flag)`
Test if the given Flags are set in this message.
`void`
`removeHeader(String name)`
Remove all headers with this name.
`void`
`setContentID(String cid)`
Set the "Content-ID" header field of this Message.
`void`
`setContentLanguage(String[] languages)`
Set the "Content-Language" header of this MimePart.
`void`
`setContentMD5(String md5)`
Set the "Content-MD5" header field of this Message.
`void`
`setDataHandler(DataHandler content)`
This method provides the mechanism to set this part's content.
`void`
`setDescription(String description, String charset)`
Set the "Content-Description" header field for this Message.
`void`
`setDisposition(String disposition)`
Set the disposition in the "Content-Disposition" header field of this body part.
`protected void`
`setExpunged(boolean set)`
Sets the expunged flag for this Message.
`void`
`setFileName(String filename)`
Set the filename associated with this part, if possible.
`void`
`setFlags(Flags flag, boolean set)`
Set/Unset the given flags in this message.
`void`
`setFrom(Address address)`
Set the RFC 822 "From" header field.
`void`
`setHeader(String name, String value)`
Set the value for this header_name.
`protected void`
`setMessageNumber(int msgnum)`
Wrapper around the protected method Message.setMessageNumber() to make that method accessible to IMAPFolder.
`void`
`setPeek(boolean peek)`
Set whether or not to use the PEEK variant of FETCH when fetching message content.
`void`
`setRecipients(Message.RecipientType type, Address[] addresses)`
Set the specified recipient type to the given addresses.
`void`
`setReplyTo(Address[] addresses)`
Set the RFC 822 "Reply-To" header field.
`void`
`setSender(Address address)`
Set the RFC 822 "Sender" header field.
`void`
`setSentDate(Date d)`
Set the RFC 822 "Date" header field.
`void`
`setSubject(String subject, String charset)`
Set the "Subject" header field.
`protected void`
`setUID(long uid)`
`void`
`writeTo(OutputStream os)`
Write out the bytes into the given OutputStream.

### Methods inherited from class javax.mail.internet.MimeMessage

`addRecipients, createInternetHeaders, createMimeMessage, getAllRecipients, getContent, getInputStream, getRawInputStream, isMimeType, parse, reply, reply, saveChanges, setContent, setContent, setDescription, setFrom, setFrom, setRecipients, setSubject, setText, setText, setText, updateHeaders, updateMessageID, writeTo`

### Methods inherited from class javax.mail.Message

`addRecipient, getFolder, getMessageNumber, getSession, isExpunged, match, setFlag, setRecipient`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Field Details

### bs

protected BODYSTRUCTURE bs

### envelope

protected ENVELOPE envelope

### items

protected Map<String,Object> items
A map of the extension FETCH items. In addition to saving the data in this map, an entry in this map indicates that we *have* the data, and so it doesn't need to be fetched again. The map is created only when needed, to avoid significantly increasing the effective size of an IMAPMessage object.

Since:
  JavaMail 1.4.6

### sectionId

protected String sectionId

## Constructor Details

### IMAPMessage

protected IMAPMessage(IMAPFolder folder, int msgnum)
Constructor.

Parameters:
  `folder` - the folder containing this message
  `msgnum` - the message sequence number

### IMAPMessage

protected IMAPMessage(Session session)
Constructor, for use by IMAPNestedMessage.

Parameters:
  `session` - the Session

## Method Details

### getProtocol

protected IMAPProtocol getProtocol() throws ProtocolException, FolderClosedException
Get this message's folder's protocol connection. Throws FolderClosedException, if the protocol connection is not available. ASSERT: Must hold the messageCacheLock.

Returns:
  the IMAPProtocol object for the containing folder
Throws:
  `ProtocolException` - for protocol errors
  `FolderClosedException` - if the folder is closed

### isREV1

protected boolean isREV1() throws FolderClosedException

Throws:
  `FolderClosedException`

### getMessageCacheLock

protected Object getMessageCacheLock()
Get the messageCacheLock, associated with this Message's Folder.

Returns:
  the message cache lock object

### getSequenceNumber

protected int getSequenceNumber()
Get this message's IMAP sequence number. ASSERT: This method must be called only when holding the messageCacheLock.

Returns:
  the message sequence number

### setMessageNumber

protected void setMessageNumber(int msgnum)
Wrapper around the protected method Message.setMessageNumber() to make that method accessible to IMAPFolder.

Overrides:
  `setMessageNumber` in class `Message`
Parameters:
  `msgnum` - the message number

### getUID

protected long getUID()
Return the UID for this message. Returns -1 if not known; use UIDFolder.getUID() in this case.

Returns:
  the UID
See Also:
  - `UIDFolder.getUID(javax.mail.Message)`

### setUID

protected void setUID(long uid)

### getModSeq

public long getModSeq() throws MessagingException
Return the modification sequence number (MODSEQ) for this message. Returns -1 if not known.

Returns:
  the modification sequence number
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.5.1
See Also:
  - "RFC 4551"

### setExpunged

protected void setExpunged(boolean set)
Description copied from class: `Message`
Sets the expunged flag for this Message. This method is to be used only by the implementation classes.

Overrides:
  `setExpunged` in class `Message`
Parameters:
  `set` - the expunged flag

### checkExpunged

protected void checkExpunged() throws MessageRemovedException

Throws:
  `MessageRemovedException`

### forceCheckExpunged

protected void forceCheckExpunged() throws MessageRemovedException, FolderClosedException
Do a NOOP to force any untagged EXPUNGE responses and then check if this message is expunged.

Throws:
  `MessageRemovedException` - if the message has been removed
  `FolderClosedException` - if the folder has been closed

### getFetchBlockSize

protected int getFetchBlockSize()

### ignoreBodyStructureSize

protected boolean ignoreBodyStructureSize()

### getFrom

public Address[] getFrom() throws MessagingException
Get the "From" attribute.

Overrides:
  `getFrom` in class `MimeMessage`
Returns:
  Address object
Throws:
  `MessagingException` - for failures
See Also:
  - `MimeMessage.headers`

### setFrom

public void setFrom(Address address) throws MessagingException
Description copied from class: `MimeMessage`
Set the RFC 822 "From" header field. Any existing values are replaced with the given address. If address is `null`, this header is removed.

Overrides:
  `setFrom` in class `MimeMessage`
Parameters:
  `address` - the sender of this message
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification of existing values
  `MessagingException` - for other failures

### addFrom

public void addFrom(Address[] addresses) throws MessagingException
Description copied from class: `MimeMessage`
Add the specified addresses to the existing "From" field. If the "From" field does not already exist, it is created.

Overrides:
  `addFrom` in class `MimeMessage`
Parameters:
  `addresses` - the senders of this message
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification of existing values
  `MessagingException` - for other failures

### getSender

public Address getSender() throws MessagingException
Get the "Sender" attribute.

Overrides:
  `getSender` in class `MimeMessage`
Returns:
  Address object
Throws:
  `MessagingException` - for failures
See Also:
  - `MimeMessage.headers`

### setSender

public void setSender(Address address) throws MessagingException
Description copied from class: `MimeMessage`
Set the RFC 822 "Sender" header field. Any existing values are replaced with the given address. If address is `null`, this header is removed.

Overrides:
  `setSender` in class `MimeMessage`
Parameters:
  `address` - the sender of this message
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification of existing values
  `MessagingException` - for other failures

### getRecipients

public Address[] getRecipients(Message.RecipientType type) throws MessagingException
Get the desired Recipient type.

Overrides:
  `getRecipients` in class `MimeMessage`
Parameters:
  `type` - Type of recepient
Returns:
  array of Address objects
Throws:
  `MessagingException` - if header could not be retrieved
  `AddressException` - if the header is misformatted
See Also:
  - `MimeMessage.headers`
  - `Message.RecipientType.TO`
  - `Message.RecipientType.CC`
  - `Message.RecipientType.BCC`
  - `MimeMessage.RecipientType.NEWSGROUPS`

### setRecipients

public void setRecipients(Message.RecipientType type, Address[] addresses) throws MessagingException
Description copied from class: `MimeMessage`
Set the specified recipient type to the given addresses. If the address parameter is `null`, the corresponding recipient field is removed.

Overrides:
  `setRecipients` in class `MimeMessage`
Parameters:
  `type` - Recipient type
  `addresses` - Addresses
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification of existing values
  `MessagingException` - for other failures
See Also:
  - `MimeMessage.getRecipients(javax.mail.Message.RecipientType)`

### addRecipients

public void addRecipients(Message.RecipientType type, Address[] addresses) throws MessagingException
Description copied from class: `MimeMessage`
Add the given addresses to the specified recipient type.

Overrides:
  `addRecipients` in class `MimeMessage`
Parameters:
  `type` - Recipient type
  `addresses` - Addresses
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification of existing values
  `MessagingException` - for other failures

### getReplyTo

public Address[] getReplyTo() throws MessagingException
Get the ReplyTo addresses.

Overrides:
  `getReplyTo` in class `MimeMessage`
Returns:
  addresses to which replies should be directed
Throws:
  `MessagingException` - for failures
See Also:
  - `MimeMessage.headers`

### setReplyTo

public void setReplyTo(Address[] addresses) throws MessagingException
Description copied from class: `MimeMessage`
Set the RFC 822 "Reply-To" header field. If the address parameter is `null`, this header is removed.

Overrides:
  `setReplyTo` in class `MimeMessage`
Parameters:
  `addresses` - addresses to which replies should be directed
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification of existing values
  `MessagingException` - for other failures

### getSubject

public String getSubject() throws MessagingException
Get the decoded subject.

Overrides:
  `getSubject` in class `MimeMessage`
Returns:
  Subject
Throws:
  `MessagingException` - for failures
See Also:
  - `MimeMessage.headers`

### setSubject

public void setSubject(String subject, String charset) throws MessagingException
Description copied from class: `MimeMessage`
Set the "Subject" header field. If the subject contains non US-ASCII characters, it will be encoded using the specified charset. If the subject contains only US-ASCII characters, no encoding is done and it is used as-is. If the subject is null, the existing "Subject" header field is removed.

The application must ensure that the subject does not contain any line breaks.

Note that if the charset encoding process fails, a MessagingException is thrown, and an UnsupportedEncodingException is included in the chain of nested exceptions within the MessagingException.

Overrides:
  `setSubject` in class `MimeMessage`
Parameters:
  `subject` - The subject
  `charset` - The charset
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification of existing values
  `MessagingException` - for other failures

### getSentDate

public Date getSentDate() throws MessagingException
Get the SentDate.

Overrides:
  `getSentDate` in class `MimeMessage`
Returns:
  The sent Date
Throws:
  `MessagingException` - for failures

### setSentDate

public void setSentDate(Date d) throws MessagingException
Description copied from class: `MimeMessage`
Set the RFC 822 "Date" header field. This is the date on which the creator of the message indicates that the message is complete and ready for delivery. If the date parameter is `null`, the existing "Date" field is removed.

Overrides:
  `setSentDate` in class `MimeMessage`
Parameters:
  `d` - the sent date of this message
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures

### getReceivedDate

public Date getReceivedDate() throws MessagingException
Get the received date (INTERNALDATE).

Overrides:
  `getReceivedDate` in class `MimeMessage`
Returns:
  the date this message was received
Throws:
  `MessagingException` - for failures

### getSize

public int getSize() throws MessagingException
Get the message size.

Note that this returns RFC822.SIZE. That is, it's the size of the whole message, header and body included. Note also that if the size of the message is greater than Integer.MAX_VALUE (2GB), this method returns Integer.MAX_VALUE.

Specified by:
  `getSize` in interface `Part`
Overrides:
  `getSize` in class `MimeMessage`
Returns:
  size of content in bytes
Throws:
  `MessagingException` - for failures

### getSizeLong

public long getSizeLong() throws MessagingException
Get the message size as a long.

Suitable for messages that might be larger than 2GB.

Returns:
  the message size as a long integer
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.6

### getLineCount

public int getLineCount() throws MessagingException
Get the total number of lines.

Returns the "body_fld_lines" field from the BODYSTRUCTURE. Note that this field is available only for text/plain and message/rfc822 types

Specified by:
  `getLineCount` in interface `Part`
Overrides:
  `getLineCount` in class `MimeMessage`
Returns:
  number of lines in the content.
Throws:
  `MessagingException` - for failures

### getContentLanguage

public String[] getContentLanguage() throws MessagingException
Get the content language.

Specified by:
  `getContentLanguage` in interface `MimePart`
Overrides:
  `getContentLanguage` in class `MimeMessage`
Returns:
  value of content-language header.
Throws:
  `MessagingException` - for failures

### setContentLanguage

public void setContentLanguage(String[] languages) throws MessagingException
Description copied from class: `MimeMessage`
Set the "Content-Language" header of this MimePart. The Content-Language header is defined by RFC 1766.

Specified by:
  `setContentLanguage` in interface `MimePart`
Overrides:
  `setContentLanguage` in class `MimeMessage`
Parameters:
  `languages` - array of language tags
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures

### getInReplyTo

public String getInReplyTo() throws MessagingException
Get the In-Reply-To header.

Returns:
  the In-Reply-To header
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.3.3

### getContentType

public String getContentType() throws MessagingException
Get the Content-Type. Generate this header from the BODYSTRUCTURE. Append parameters as well.

Specified by:
  `getContentType` in interface `Part`
Overrides:
  `getContentType` in class `MimeMessage`
Returns:
  The ContentType of this part
Throws:
  `MessagingException` - for failures
See Also:
  - `DataHandler`

### getDisposition

public String getDisposition() throws MessagingException
Get the Content-Disposition.

Specified by:
  `getDisposition` in interface `Part`
Overrides:
  `getDisposition` in class `MimeMessage`
Returns:
  disposition of this part, or null if unknown
Throws:
  `MessagingException` - for failures
See Also:
  - `Part.ATTACHMENT`
  - `Part.INLINE`
  - `Part.getFileName()`

### setDisposition

public void setDisposition(String disposition) throws MessagingException
Description copied from class: `MimeMessage`
Set the disposition in the "Content-Disposition" header field of this body part. If the disposition is null, any existing "Content-Disposition" header field is removed.

Specified by:
  `setDisposition` in interface `Part`
Overrides:
  `setDisposition` in class `MimeMessage`
Parameters:
  `disposition` - disposition of this part
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures
See Also:
  - `Part.ATTACHMENT`
  - `Part.INLINE`
  - `Part.setFileName(java.lang.String)`

### getEncoding

public String getEncoding() throws MessagingException
Get the Content-Transfer-Encoding.

Specified by:
  `getEncoding` in interface `MimePart`
Overrides:
  `getEncoding` in class `MimeMessage`
Returns:
  content-transfer-encoding
Throws:
  `MessagingException` - for failures

### getContentID

public String getContentID() throws MessagingException
Get the Content-ID.

Specified by:
  `getContentID` in interface `MimePart`
Overrides:
  `getContentID` in class `MimeMessage`
Returns:
  content-ID
Throws:
  `MessagingException` - for failures

### setContentID

public void setContentID(String cid) throws MessagingException
Description copied from class: `MimeMessage`
Set the "Content-ID" header field of this Message. If the `cid` parameter is null, any existing "Content-ID" is removed.

Overrides:
  `setContentID` in class `MimeMessage`
Parameters:
  `cid` - the content ID
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures

### getContentMD5

public String getContentMD5() throws MessagingException
Get the Content-MD5.

Specified by:
  `getContentMD5` in interface `MimePart`
Overrides:
  `getContentMD5` in class `MimeMessage`
Returns:
  content-MD5
Throws:
  `MessagingException` - for failures

### setContentMD5

public void setContentMD5(String md5) throws MessagingException
Description copied from class: `MimeMessage`
Set the "Content-MD5" header field of this Message.

Specified by:
  `setContentMD5` in interface `MimePart`
Overrides:
  `setContentMD5` in class `MimeMessage`
Parameters:
  `md5` - the MD5 value
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures

### getDescription

public String getDescription() throws MessagingException
Get the decoded Content-Description.

Specified by:
  `getDescription` in interface `Part`
Overrides:
  `getDescription` in class `MimeMessage`
Returns:
  content-description
Throws:
  `MessagingException` - for failures

### setDescription

public void setDescription(String description, String charset) throws MessagingException
Description copied from class: `MimeMessage`
Set the "Content-Description" header field for this Message. If the description parameter is `null`, then any existing "Content-Description" fields are removed.

If the description contains non US-ASCII characters, it will be encoded using the specified charset. If the description contains only US-ASCII characters, no encoding is done and it is used as-is.

Note that if the charset encoding process fails, a MessagingException is thrown, and an UnsupportedEncodingException is included in the chain of nested exceptions within the MessagingException.

Overrides:
  `setDescription` in class `MimeMessage`
Parameters:
  `description` - Description
  `charset` - Charset for encoding
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - An UnsupportedEncodingException may be included in the exception chain if the charset conversion fails.

### getMessageID

public String getMessageID() throws MessagingException
Get the Message-ID.

Overrides:
  `getMessageID` in class `MimeMessage`
Returns:
  Message-ID
Throws:
  `MessagingException` - if the retrieval of this field causes any exception.
See Also:
  - `MessageIDTerm`

### getFileName

public String getFileName() throws MessagingException
Get the "filename" Disposition parameter. (Only available in IMAP4rev1). If thats not available, get the "name" ContentType parameter.

Specified by:
  `getFileName` in interface `Part`
Overrides:
  `getFileName` in class `MimeMessage`
Returns:
  filename
Throws:
  `MessagingException` - for failures

### setFileName

public void setFileName(String filename) throws MessagingException
Description copied from class: `MimeMessage`
Set the filename associated with this part, if possible.

Sets the "filename" parameter of the "Content-Disposition" header field of this message.

If the `mail.mime.encodefilename` System property is set to true, the `MimeUtility.encodeText` method will be used to encode the filename. While such encoding is not supported by the MIME spec, many mailers use this technique to support non-ASCII characters in filenames. The default value of this property is false.

Specified by:
  `setFileName` in interface `Part`
Overrides:
  `setFileName` in class `MimeMessage`
Parameters:
  `filename` - Filename to associate with this part
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures

### getContentStream

protected InputStream getContentStream() throws MessagingException
Get all the bytes for this message. Overrides getContentStream() in MimeMessage. This method is ultimately used by the DataHandler to obtain the input stream for this message.

Overrides:
  `getContentStream` in class `MimeMessage`
Returns:
  an InputStream containing the raw bytes
Throws:
  `MessagingException` - for failures
See Also:
  - `MimeMessage.getContentStream()`

### getDataHandler

public DataHandler getDataHandler() throws MessagingException
Get the DataHandler object for this message.

Specified by:
  `getDataHandler` in interface `Part`
Overrides:
  `getDataHandler` in class `MimeMessage`
Returns:
  DataHandler for the content
Throws:
  `MessagingException` - for failures

### setDataHandler

public void setDataHandler(DataHandler content) throws MessagingException
Description copied from class: `MimeMessage`
This method provides the mechanism to set this part's content. The given DataHandler object should wrap the actual content.

Specified by:
  `setDataHandler` in interface `Part`
Overrides:
  `setDataHandler` in class `MimeMessage`
Parameters:
  `content` - The DataHandler for the content.
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures

### getMimeStream

public InputStream getMimeStream() throws MessagingException
Return the MIME format stream corresponding to this message.

Specified by:
  `getMimeStream` in interface `ReadableMime`
Returns:
  the MIME format stream
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.4.5

### writeTo

public void writeTo(OutputStream os) throws IOException, MessagingException
Write out the bytes into the given OutputStream.

Specified by:
  `writeTo` in interface `Part`
Overrides:
  `writeTo` in class `MimeMessage`
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 javax.activation layer.
  `MessagingException` - for other failures
See Also:
  - `DataHandler.writeTo(java.io.OutputStream)`

### getHeader

public String[] getHeader(String name) throws MessagingException
Get the named header.

Specified by:
  `getHeader` in interface `Part`
Overrides:
  `getHeader` in class `MimeMessage`
Parameters:
  `name` - name of header
Returns:
  array of headers
Throws:
  `MessagingException` - for failures
See Also:
  - `MimeUtility`

### getHeader

public String getHeader(String name, String delimiter) throws MessagingException
Get the named header.

Specified by:
  `getHeader` in interface `MimePart`
Overrides:
  `getHeader` in class `MimeMessage`
Parameters:
  `name` - the name of this header
  `delimiter` - separator between values
Returns:
  the value fields for all headers with this name
Throws:
  `MessagingException` - for failures

### setHeader

public void setHeader(String name, String value) throws MessagingException
Description copied from class: `MimeMessage`
Set the value for this header_name. Replaces all existing header values with this new value. Note that RFC 822 headers must contain only US-ASCII characters, so a header that contains non US-ASCII characters must have been encoded by the caller as per the rules of RFC 2047.

Specified by:
  `setHeader` in interface `Part`
Overrides:
  `setHeader` in class `MimeMessage`
Parameters:
  `name` - header name
  `value` - header value
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures
See Also:
  - `MimeUtility`

### addHeader

public void addHeader(String name, String value) throws MessagingException
Description copied from class: `MimeMessage`
Add this value to the existing values for this header_name. Note that RFC 822 headers must contain only US-ASCII characters, so a header that contains non US-ASCII characters must have been encoded as per the rules of RFC 2047.

Specified by:
  `addHeader` in interface `Part`
Overrides:
  `addHeader` in class `MimeMessage`
Parameters:
  `name` - header name
  `value` - header value
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures
See Also:
  - `MimeUtility`

### removeHeader

public void removeHeader(String name) throws MessagingException
Description copied from class: `MimeMessage`
Remove all headers with this name.

Specified by:
  `removeHeader` in interface `Part`
Overrides:
  `removeHeader` in class `MimeMessage`
Parameters:
  `name` - the name of this header
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures

### getAllHeaders

public Enumeration<Header> getAllHeaders() throws MessagingException
Get all headers.

Specified by:
  `getAllHeaders` in interface `Part`
Overrides:
  `getAllHeaders` in class `MimeMessage`
Returns:
  array of header objects
Throws:
  `MessagingException` - for failures
See Also:
  - `MimeUtility`

### getMatchingHeaders

public Enumeration<Header> getMatchingHeaders(String[] names) throws MessagingException
Get matching headers.

Specified by:
  `getMatchingHeaders` in interface `Part`
Overrides:
  `getMatchingHeaders` in class `MimeMessage`
Parameters:
  `names` - the headers to match
Returns:
  enumeration of Header objects
Throws:
  `MessagingException` - for failures

### getNonMatchingHeaders

public Enumeration<Header> getNonMatchingHeaders(String[] names) throws MessagingException
Get non-matching headers.

Specified by:
  `getNonMatchingHeaders` in interface `Part`
Overrides:
  `getNonMatchingHeaders` in class `MimeMessage`
Parameters:
  `names` - the headers to not match
Returns:
  enumeration of Header objects
Throws:
  `MessagingException` - for failures

### addHeaderLine

public void addHeaderLine(String line) throws MessagingException
Description copied from class: `MimeMessage`
Add a raw RFC 822 header-line.

Specified by:
  `addHeaderLine` in interface `MimePart`
Overrides:
  `addHeaderLine` in class `MimeMessage`
Parameters:
  `line` - the line to add
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures

### getAllHeaderLines

public Enumeration<String> getAllHeaderLines() throws MessagingException
Get all header-lines.

Specified by:
  `getAllHeaderLines` in interface `MimePart`
Overrides:
  `getAllHeaderLines` in class `MimeMessage`
Returns:
  an Enumeration of Strings
Throws:
  `MessagingException` - for failures

### getMatchingHeaderLines

public Enumeration<String> getMatchingHeaderLines(String[] names) throws MessagingException
Get all matching header-lines.

Specified by:
  `getMatchingHeaderLines` in interface `MimePart`
Overrides:
  `getMatchingHeaderLines` in class `MimeMessage`
Parameters:
  `names` - the headers to return
Returns:
  an Enumeration of Strings
Throws:
  `MessagingException` - for failures

### getNonMatchingHeaderLines

public Enumeration<String> getNonMatchingHeaderLines(String[] names) throws MessagingException
Get all non-matching headerlines.

Specified by:
  `getNonMatchingHeaderLines` in interface `MimePart`
Overrides:
  `getNonMatchingHeaderLines` in class `MimeMessage`
Parameters:
  `names` - the headers to not return
Returns:
  an Enumeration of Strings
Throws:
  `MessagingException` - for failures

### getFlags

public Flags getFlags() throws MessagingException
Get the Flags for this message.

Overrides:
  `getFlags` in class `MimeMessage`
Returns:
  Flags object containing the flags for this message
Throws:
  `MessagingException` - for failures
See Also:
  - `Flags`

### isSet

public boolean isSet(Flags.Flag flag) throws MessagingException
Test if the given Flags are set in this message.

Overrides:
  `isSet` in class `MimeMessage`
Parameters:
  `flag` - the flag
Returns:
  value of the specified flag for this message
Throws:
  `MessagingException` - for failures
See Also:
  - `Flags.Flag`
  - `Flags.Flag.ANSWERED`
  - `Flags.Flag.DELETED`
  - `Flags.Flag.DRAFT`
  - `Flags.Flag.FLAGGED`
  - `Flags.Flag.RECENT`
  - `Flags.Flag.SEEN`

### setFlags

public void setFlags(Flags flag, boolean set) throws MessagingException
Set/Unset the given flags in this message.

Overrides:
  `setFlags` in class `MimeMessage`
Parameters:
  `flag` - Flags object containing the flags to be set
  `set` - the value to be set
Throws:
  `IllegalWriteException` - if the underlying implementation does not support modification
  `MessagingException` - for other failures
See Also:
  - `MessageChangedEvent`

### setPeek

public void setPeek(boolean peek)
Set whether or not to use the PEEK variant of FETCH when fetching message content. This overrides the default value from the "mail.imap.peek" property.

Parameters:
  `peek` - the peek flag
Since:
  JavaMail 1.3.3

### getPeek

public boolean getPeek()
Get whether or not to use the PEEK variant of FETCH when fetching message content.

Returns:
  the peek flag
Since:
  JavaMail 1.3.3

### invalidateHeaders

public void invalidateHeaders()
Invalidate cached header and envelope information for this message. Subsequent accesses of this information will cause it to be fetched from the server.

Since:
  JavaMail 1.3.3

### handleFetchItem

protected boolean handleFetchItem(Item item, String[] hdrs, boolean allHeaders) throws MessagingException
Apply the data in the FETCH item to this message. ASSERT: Must hold the messageCacheLock.

Parameters:
  `item` - the fetch item
  `hdrs` - the headers we're asking for
  `allHeaders` - load all headers?
Returns:
  did we handle this fetch item?
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.4.6

### handleExtensionFetchItems

protected void handleExtensionFetchItems(Map<String,Object> extensionItems)
Apply the data in the extension FETCH items to this message. This method adds all the items to the items map. Subclasses may override this method to call super and then also copy the data to a more convenient form. ASSERT: Must hold the messageCacheLock.

Parameters:
  `extensionItems` - the Map to add fetch items to
Since:
  JavaMail 1.4.6

### fetchItem

protected Object fetchItem(FetchItem fitem) throws MessagingException
Fetch an individual item for the current message. Note that handleExtensionFetchItems will have been called to store this item in the message before this method returns.

Parameters:
  `fitem` - the FetchItem
Returns:
  the data associated with the FetchItem
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.4.6

### getItem

public Object getItem(FetchItem fitem) throws MessagingException
Return the data associated with the FetchItem. If the data hasn't been fetched, call the fetchItem method to fetch it. Returns null if there is no data for the FetchItem.

Parameters:
  `fitem` - the FetchItem
Returns:
  the data associated with the FetchItem
Throws:
  `MessagingException` - for failures
Since:
  JavaMail 1.4.6