Package com.sun.mail.pop3

## Class POP3Message

- java.lang.Object
- - javax.mail.Message
  - - javax.mail.internet.MimeMessage
    - - com.sun.mail.pop3.POP3Message

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

    public class POP3Message
    extends MimeMessage
    implements ReadableMime

A POP3 Message. Just like a MimeMessage except that some things are not supported.

Author:
  Bill Shannon

### Nested Class Summary

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

`MimeMessage.RecipientType`

### Field Summary

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

`expunged, msgnum, session`

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

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

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

`ATTACHMENT, INLINE`

### Constructor Summary

Constructors
`POP3Message​(Folder folder, int msgno)`

### Method Summary

All Methods Instance Methods Concrete Methods
`void` `addHeader​(String name, String value)` Add this value to the existing values for this header_name.
`void` `addHeaderLine​(String line)` Add a raw RFC822 header-line.
`Enumeration<String>` `getAllHeaderLines​()` Get all header lines as an Enumeration of Strings.
`Enumeration<Header>` `getAllHeaders​()` Return all the headers from this Message as an enumeration of Header objects.
`protected InputStream` `getContentStream​()` Produce the raw bytes of the content.
`String[]` `getHeader​(String name)` Get all the headers for this header_name.
`String` `getHeader​(String name, String delimiter)` Get all the headers for this header name, returned as a single String, with headers separated by the delimiter.
`Enumeration<String>` `getMatchingHeaderLines​(String[] names)` Get matching header lines as an Enumeration of Strings.
`Enumeration<Header>` `getMatchingHeaders​(String[] names)` Return matching headers from this Message as an Enumeration of Header objects.
`InputStream` `getMimeStream​()` Return the MIME format stream corresponding to this message part.
`Enumeration<String>` `getNonMatchingHeaderLines​(String[] names)` Get non-matching header lines as an Enumeration of Strings.
`Enumeration<Header>` `getNonMatchingHeaders​(String[] names)` Return non-matching headers from this Message as an Enumeration of Header objects.
`int` `getSize​()` Return the size of the content of this message in bytes.
`void` `invalidate​(boolean invalidateHeaders)` Invalidate the cache of content for this message object, causing it to be fetched again from the server the next time it is needed.
`void` `removeHeader​(String name)` Remove all headers with this name.
`void` `saveChanges​()` POP3 message can't be changed.
`void` `setFlags​(Flags newFlags, boolean set)` Set the specified flags on this message to the specified value.
`void` `setHeader​(String name, String value)` Set the value for this header_name.
`InputStream` `top​(int n)` Fetch the header of the message and the first `n` lines of the raw content of the message.
`void` `writeTo​(OutputStream os, String[] ignoreList)` Output the message as an RFC 822 format stream, without specified headers.

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

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

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

`addFrom, addRecipients, addRecipients, createInternetHeaders, createMimeMessage, getAllRecipients, getContent, getContentID, getContentLanguage, getContentMD5, getContentType, getDataHandler, getDescription, getDisposition, getEncoding, getFileName, getFlags, getFrom, getInputStream, getLineCount, getMessageID, getRawInputStream, getReceivedDate, getRecipients, getReplyTo, getSender, getSentDate, getSubject, isMimeType, isSet, parse, reply, reply, setContent, setContent, setContentID, setContentLanguage, setContentMD5, setDataHandler, setDescription, setDescription, setDisposition, setFileName, setFrom, setFrom, setFrom, setRecipients, setRecipients, setReplyTo, setSender, setSentDate, setSubject, setSubject, setText, setText, setText, updateHeaders, updateMessageID, writeTo`

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

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

### Constructor Detail

#### POP3Message

    public POP3Message​(Folder folder,
                       int msgno)
                throws MessagingException

Throws:
  `MessagingException`

### Method Detail

#### setFlags

    public void setFlags​(Flags newFlags,
                         boolean set)
                  throws MessagingException

Set the specified flags on this message to the specified value.

Overrides:
  `setFlags` in class `MimeMessage`
Parameters:
  `newFlags` - 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`

#### getSize

    public int getSize​()
                throws MessagingException

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

Note that this number may not be an exact measure of the content size and may or may not account for any transfer encoding of the content.

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

#### getContentStream

    protected InputStream getContentStream​()
                                    throws MessagingException

Produce the raw bytes of the content. The data is fetched using the POP3 RETR command.

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

#### getMimeStream

    public InputStream getMimeStream​()
                              throws MessagingException

Return the MIME format stream corresponding to this message part.

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

#### invalidate

    public void invalidate​(boolean invalidateHeaders)

Invalidate the cache of content for this message object, causing it to be fetched again from the server the next time it is needed. If `invalidateHeaders` is true, invalidate the headers as well.

Parameters:
  `invalidateHeaders` - invalidate the headers as well?

#### top

    public InputStream top​(int n)
                    throws MessagingException

Fetch the header of the message and the first `n` lines of the raw content of the message. The headers and data are available in the returned InputStream.

Parameters:
  `n` - number of lines of content to fetch
Returns:
  InputStream containing the message headers and n content lines
Throws:
  `MessagingException` - for failures

#### getHeader

    public String[] getHeader​(String name)
                       throws MessagingException

Get all the headers for this header_name. Note that certain headers may be encoded as per RFC 2047 if they contain non US-ASCII characters and these should be decoded.

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 all the headers for this header name, returned as a single String, with headers separated by the delimiter. If the delimiter is `null`, only the first header is returned.

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

#### setHeader

    public void setHeader​(String name,
                          String value)
                   throws MessagingException

Set the value for this header_name. Throws IllegalWriteException because POP3 messages are read-only.

Specified by:
  `setHeader` in interface `Part`
Overrides:
  `setHeader` in class `MimeMessage`
Parameters:
  `name` - header name
  `value` - header value
Throws:
  `IllegalWriteException` - because the underlying implementation does not support modification
  `IllegalStateException` - if this message is obtained from a READ_ONLY folder.
  `MessagingException` - for other failures
See Also:
  `MimeUtility`

#### addHeader

    public void addHeader​(String name,
                          String value)
                   throws MessagingException

Add this value to the existing values for this header_name. Throws IllegalWriteException because POP3 messages are read-only.

Specified by:
  `addHeader` in interface `Part`
Overrides:
  `addHeader` in class `MimeMessage`
Parameters:
  `name` - header name
  `value` - header value
Throws:
  `IllegalWriteException` - because the underlying implementation does not support modification
  `IllegalStateException` - if this message is obtained from a READ_ONLY folder.
  `MessagingException` - for other failures
See Also:
  `MimeUtility`

#### removeHeader

    public void removeHeader​(String name)
                      throws MessagingException

Remove all headers with this name. Throws IllegalWriteException because POP3 messages are read-only.

Specified by:
  `removeHeader` in interface `Part`
Overrides:
  `removeHeader` in class `MimeMessage`
Parameters:
  `name` - the name of this header
Throws:
  `IllegalWriteException` - because the underlying implementation does not support modification
  `IllegalStateException` - if this message is obtained from a READ_ONLY folder.
  `MessagingException` - for other failures

#### getAllHeaders

    public Enumeration<Header> getAllHeaders​()
                                      throws MessagingException

Return all the headers from this Message as an enumeration of Header objects.

Note that certain headers may be encoded as per RFC 2047 if they contain non US-ASCII characters and these should be decoded.

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

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

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

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

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

Add a raw RFC822 header-line. Throws IllegalWriteException because POP3 messages are read-only.

Specified by:
  `addHeaderLine` in interface `MimePart`
Overrides:
  `addHeaderLine` in class `MimeMessage`
Parameters:
  `line` - the line to add
Throws:
  `IllegalWriteException` - because the underlying implementation does not support modification
  `IllegalStateException` - if this message is obtained from a READ_ONLY folder.
  `MessagingException` - for other failures

#### getAllHeaderLines

    public Enumeration<String> getAllHeaderLines​()
                                          throws MessagingException

Get all header lines as an Enumeration of Strings. A Header line is a raw RFC822 header-line, containing both the "name" and "value" field.

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 matching header lines as an Enumeration of Strings. A Header line is a raw RFC822 header-line, containing both the "name" and "value" field.

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 non-matching header lines as an Enumeration of Strings. A Header line is a raw RFC822 header-line, containing both the "name" and "value" field.

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

#### saveChanges

    public void saveChanges​()
                     throws MessagingException

POP3 message can't be changed. This method throws IllegalWriteException.

Overrides:
  `saveChanges` in class `MimeMessage`
Throws:
  `IllegalWriteException` - because the underlying implementation does not support modification
  `MessagingException` - for other failures

#### writeTo

    public void writeTo​(OutputStream os,
                        String[] ignoreList)
                 throws IOException,
                        MessagingException

Output the message as an RFC 822 format stream, without specified headers. If the property "mail.pop3.cachewriteto" is set to "true", and ignoreList is null, and the message hasn't already been cached as a side effect of other operations, the message content is cached before being written. Otherwise, the message is streamed directly to the output stream without being cached.

Overrides:
  `writeTo` in class `MimeMessage`
Parameters:
  `os` - the stream to write to
  `ignoreList` - the headers to not include in the output
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)`