Class IMAPMessage

  • All Implemented Interfaces:
    ReadableMime, MimePart, Part

    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.

    • Field Detail

      • bs

        protected com.sun.mail.imap.protocol.BODYSTRUCTURE bs
      • envelope

        protected com.sun.mail.imap.protocol.ENVELOPE envelope
      • items

        protected java.util.Map<java.lang.String,​java.lang.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 java.lang.String sectionId
    • Constructor Detail

      • 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 Detail

      • getProtocol

        protected com.sun.mail.imap.protocol.IMAPProtocol getProtocol()
                                                               throws com.sun.mail.iap.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:
        com.sun.mail.iap.ProtocolException - for protocol errors
        FolderClosedException - if the folder is closed
      • getMessageCacheLock

        protected java.lang.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
      • getFetchBlockSize

        protected int getFetchBlockSize()
      • ignoreBodyStructureSize

        protected boolean ignoreBodyStructureSize()
      • 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
      • 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
      • 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
      • setSubject

        public void setSubject​(java.lang.String subject,
                               java.lang.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
      • setSentDate

        public void setSentDate​(java.util.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
      • 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
      • getInReplyTo

        public java.lang.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
      • setContentID

        public void setContentID​(java.lang.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
      • setDescription

        public void setDescription​(java.lang.String description,
                                   java.lang.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.
      • getFileName

        public java.lang.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​(java.lang.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
      • setDataHandler

        public void setDataHandler​(javax.activation.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
      • writeTo

        public void writeTo​(java.io.OutputStream os)
                     throws java.io.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:
        java.io.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 java.lang.String getHeader​(java.lang.String name,
                                          java.lang.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​(java.lang.String name,
                              java.lang.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​(java.lang.String name,
                              java.lang.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
      • 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​(com.sun.mail.imap.protocol.Item item,
                                          java.lang.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​(java.util.Map<java.lang.String,​java.lang.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 java.lang.Object fetchItem​(com.sun.mail.imap.protocol.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 java.lang.Object getItem​(com.sun.mail.imap.protocol.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