javax.mail.internet

## Class MimeMultipart

- java.lang.Object
- - javax.mail.Multipart
  - - javax.mail.internet.MimeMultipart

-     public class MimeMultipart
      extends Multipart

  The MimeMultipart class is an implementation of the abstract Multipart class that uses MIME conventions for the multipart data.

  A MimeMultipart is obtained from a MimePart whose primary type is "multipart" (by invoking the part's `getContent()` method) or it can be created by a client as part of creating a new MimeMessage.

  The default multipart subtype is "mixed". The other multipart subtypes, such as "alternative", "related", and so on, can be implemented as subclasses of MimeMultipart with additional methods to implement the additional semantics of that type of multipart content. The intent is that service providers, mail JavaBean writers and mail clients will write many such subclasses and their Command Beans, and will install them into the JavaBeans Activation Framework, so that any JavaMail implementation and its clients can transparently find and use these classes. Thus, a MIME multipart handler is treated just like any other type handler, thereby decoupling the process of providing multipart handlers from the JavaMail API. Lacking these additional MimeMultipart subclasses, all subtypes of MIME multipart data appear as MimeMultipart objects.

  An application can directly construct a MIME multipart object of any subtype by using the `MimeMultipart(String subtype)` constructor. For example, to create a "multipart/alternative" object, use `new MimeMultipart("alternative")`.

  The `mail.mime.multipart.ignoremissingendboundary` property may be set to `false` to cause a `MessagingException` to be thrown if the multipart data does not end with the required end boundary line. If this property is set to `true` or not set, missing end boundaries are not considered an error and the final body part ends at the end of the data.

  The `mail.mime.multipart.ignoremissingboundaryparameter` System property may be set to `false` to cause a `MessagingException` to be thrown if the Content-Type of the MimeMultipart does not include a `boundary` parameter. If this property is set to `true` or not set, the multipart parsing code will look for a line that looks like a bounary line and use that as the boundary separating the parts.

  The `mail.mime.multipart.ignoreexistingboundaryparameter` System property may be set to `true` to cause any boundary to be ignored and instead search for a boundary line in the message as with `mail.mime.multipart.ignoremissingboundaryparameter`.

  Normally, when writing out a MimeMultipart that contains no body parts, or when trying to parse a multipart message with no body parts, a `MessagingException` is thrown. The MIME spec does not allow multipart content with no body parts. The `mail.mime.multipart.allowempty` System property may be set to `true` to override this behavior. When writing out such a MimeMultipart, a single empty part will be included. When reading such a multipart, a MimeMultipart will be created with no body parts.

  Author:
    John Mani, Bill Shannon, Max Spivak

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `allowEmpty` Flag corresponding to the "mail.mime.multipart.allowempty" property, set in the `initializeProperties()` method called from constructors and the parse method.
    `protected boolean` | `complete` Have we seen the final bounary line?
    `protected DataSource` | `ds` The DataSource supplying our InputStream.
    `protected boolean` | `ignoreExistingBoundaryParameter` Flag corresponding to the "mail.mime.multipart.ignoreexistingboundaryparameter" property, set in the `initializeProperties()` method called from constructors and the parse method.
    `protected boolean` | `ignoreMissingBoundaryParameter` Flag corresponding to the "mail.mime.multipart.ignoremissingboundaryparameter" property, set in the `initializeProperties()` method called from constructors and the parse method.
    `protected boolean` | `ignoreMissingEndBoundary` Flag corresponding to the "mail.mime.multipart.ignoremissingendboundary" property, set in the `initializeProperties()` method called from constructors and the parse method.
    `protected boolean` | `parsed` Have we parsed the data from our InputStream yet? Defaults to true; set to false when our constructor is given a DataSource with an InputStream that we need to parse.
    `protected String` | `preamble` The MIME multipart preamble text, the text that occurs before the first boundary line.

    - ### Fields inherited from class javax.mail.Multipart

      `contentType, parent, parts`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MimeMultipart()` Default constructor.
    `MimeMultipart(BodyPart... parts)` Construct a MimeMultipart object of the default "mixed" subtype, and with the given body parts.
    `MimeMultipart(DataSource ds)` Constructs a MimeMultipart object and its bodyparts from the given DataSource.
    `MimeMultipart(String subtype)` Construct a MimeMultipart object of the given subtype.
    `MimeMultipart(String subtype, BodyPart... parts)` Construct a MimeMultipart object of the given subtype and with the given body parts.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addBodyPart(BodyPart part)` Adds a Part to the multipart.
    `void` | `addBodyPart(BodyPart part, int index)` Adds a BodyPart at position `index`.
    `protected InternetHeaders` | `createInternetHeaders(InputStream is)` Create and return an InternetHeaders object that loads the headers from the given InputStream.
    `protected MimeBodyPart` | `createMimeBodyPart(InputStream is)` Create and return a MimeBodyPart object to represent a body part parsed from the InputStream.
    `protected MimeBodyPart` | `createMimeBodyPart(InternetHeaders headers, byte[] content)` Create and return a MimeBodyPart object to represent a body part parsed from the InputStream.
    `BodyPart` | `getBodyPart(int index)` Get the specified BodyPart.
    `BodyPart` | `getBodyPart(String CID)` Get the MimeBodyPart referred to by the given ContentID (CID).
    `int` | `getCount()` Return the number of enclosed BodyPart objects.
    `String` | `getPreamble()` Get the preamble text, if any, that appears before the first body part of this multipart.
    `protected void` | `initializeProperties()` Initialize flags that control parsing behavior, based on System properties described above in the class documentation.
    `boolean` | `isComplete()` Return true if the final boundary line for this multipart was seen.
    `protected void` | `parse()` Parse the InputStream from our DataSource, constructing the appropriate MimeBodyParts.
    `boolean` | `removeBodyPart(BodyPart part)` Remove the specified part from the multipart message.
    `void` | `removeBodyPart(int index)` Remove the part at specified location (starting from 0).
    `void` | `setPreamble(String preamble)` Set the preamble text to be included before the first body part.
    `void` | `setSubType(String subtype)` Set the subtype.
    `protected void` | `updateHeaders()` Update headers.
    `void` | `writeTo(OutputStream os)` Iterates through all the parts and outputs each MIME part separated by a boundary.

    - ### Methods inherited from class javax.mail.Multipart

      `getContentType, getParent, setMultipartDataSource, setParent`

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

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

- - ### Field Detail

    - #### ds

          protected DataSource ds

      The DataSource supplying our InputStream.

    - #### parsed

          protected boolean parsed

      Have we parsed the data from our InputStream yet? Defaults to true; set to false when our constructor is given a DataSource with an InputStream that we need to parse.

    - #### complete

          protected boolean complete

      Have we seen the final bounary line?
      Since:
        JavaMail 1.5

    - #### preamble

          protected String preamble

      The MIME multipart preamble text, the text that occurs before the first boundary line.
      Since:
        JavaMail 1.5

    - #### ignoreMissingEndBoundary

          protected boolean ignoreMissingEndBoundary

      Flag corresponding to the "mail.mime.multipart.ignoremissingendboundary" property, set in the `initializeProperties()` method called from constructors and the parse method.
      Since:
        JavaMail 1.5

    - #### ignoreMissingBoundaryParameter

          protected boolean ignoreMissingBoundaryParameter

      Flag corresponding to the "mail.mime.multipart.ignoremissingboundaryparameter" property, set in the `initializeProperties()` method called from constructors and the parse method.
      Since:
        JavaMail 1.5

    - #### ignoreExistingBoundaryParameter

          protected boolean ignoreExistingBoundaryParameter

      Flag corresponding to the "mail.mime.multipart.ignoreexistingboundaryparameter" property, set in the `initializeProperties()` method called from constructors and the parse method.
      Since:
        JavaMail 1.5

    - #### allowEmpty

          protected boolean allowEmpty

      Flag corresponding to the "mail.mime.multipart.allowempty" property, set in the `initializeProperties()` method called from constructors and the parse method.
      Since:
        JavaMail 1.5

  - ### Constructor Detail

    - #### MimeMultipart

          public MimeMultipart()

      Default constructor. An empty MimeMultipart object is created. Its content type is set to "multipart/mixed". A unique boundary string is generated and this string is setup as the "boundary" parameter for the `contentType` field.

      MimeBodyParts may be added later.

    - #### MimeMultipart

          public MimeMultipart(String subtype)

      Construct a MimeMultipart object of the given subtype. A unique boundary string is generated and this string is setup as the "boundary" parameter for the `contentType` field. Calls the `initializeProperties()` method.

      MimeBodyParts may be added later.

      Parameters:
        `subtype` - the MIME content subtype

    - #### MimeMultipart

          public MimeMultipart(BodyPart... parts)
                        throws MessagingException

      Construct a MimeMultipart object of the default "mixed" subtype, and with the given body parts. More body parts may be added later.
      Parameters:
        `parts` - the body parts
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.5

    - #### MimeMultipart

          public MimeMultipart(String subtype,
                       BodyPart... parts)
                        throws MessagingException

      Construct a MimeMultipart object of the given subtype and with the given body parts. More body parts may be added later.
      Parameters:
        `subtype` - the MIME content subtype
        `parts` - the body parts
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.5

    - #### MimeMultipart

          public MimeMultipart(DataSource ds)
                        throws MessagingException

      Constructs a MimeMultipart object and its bodyparts from the given DataSource.

      This constructor handles as a special case the situation where the given DataSource is a MultipartDataSource object. In this case, this method just invokes the superclass (i.e., Multipart) constructor that takes a MultipartDataSource object.

      Otherwise, the DataSource is assumed to provide a MIME multipart byte stream. The `parsed` flag is set to false. When the data for the body parts are needed, the parser extracts the "boundary" parameter from the content type of this DataSource, skips the 'preamble' and reads bytes till the terminating boundary and creates MimeBodyParts for each part of the stream.

      Parameters:
        `ds` - DataSource, can be a MultipartDataSource
      Throws:
        `MessagingException` - for failures

  - ### Method Detail

    - #### initializeProperties

          protected void initializeProperties()

      Initialize flags that control parsing behavior, based on System properties described above in the class documentation.
      Since:
        JavaMail 1.5

    - #### setSubType

          public void setSubType(String subtype)
                          throws MessagingException

      Set the subtype. This method should be invoked only on a new MimeMultipart object created by the client. The default subtype of such a multipart object is "mixed".

      Parameters:
        `subtype` - Subtype
      Throws:
        `MessagingException` - for failures

    - #### getCount

          public int getCount()
                       throws MessagingException

      Return the number of enclosed BodyPart objects.
      Overrides:
        `getCount` in class `Multipart`
      Returns:
        number of parts
      Throws:
        `MessagingException` - for failures
      See Also:
        `Multipart.parts`

    - #### getBodyPart

          public BodyPart getBodyPart(int index)
                               throws MessagingException

      Get the specified BodyPart. BodyParts are numbered starting at 0.
      Overrides:
        `getBodyPart` in class `Multipart`
      Parameters:
        `index` - the index of the desired BodyPart
      Returns:
        the Part
      Throws:
        `MessagingException` - if no such BodyPart exists

    - #### getBodyPart

          public BodyPart getBodyPart(String CID)
                               throws MessagingException

      Get the MimeBodyPart referred to by the given ContentID (CID). Returns null if the part is not found.
      Parameters:
        `CID` - the ContentID of the desired part
      Returns:
        the Part
      Throws:
        `MessagingException` - for failures

    - #### removeBodyPart

          public boolean removeBodyPart(BodyPart part)
                                 throws MessagingException

      Remove the specified part from the multipart message. Shifts all the parts after the removed part down one.
      Overrides:
        `removeBodyPart` in class `Multipart`
      Parameters:
        `part` - The part to remove
      Returns:
        true if part removed, false otherwise
      Throws:
        `MessagingException` - if no such Part exists
        `IllegalWriteException` - if the underlying implementation does not support modification of existing values

    - #### removeBodyPart

          public void removeBodyPart(int index)
                              throws MessagingException

      Remove the part at specified location (starting from 0). Shifts all the parts after the removed part down one.
      Overrides:
        `removeBodyPart` in class `Multipart`
      Parameters:
        `index` - Index of the part to remove
      Throws:
        `IndexOutOfBoundsException` - if the given index is out of range.
        `IllegalWriteException` - if the underlying implementation does not support modification of existing values
        `MessagingException` - for other failures

    - #### addBodyPart

          public void addBodyPart(BodyPart part)
                           throws MessagingException

      Adds a Part to the multipart. The BodyPart is appended to the list of existing Parts.
      Overrides:
        `addBodyPart` in class `Multipart`
      Parameters:
        `part` - The Part to be appended
      Throws:
        `IllegalWriteException` - if the underlying implementation does not support modification of existing values
        `MessagingException` - for other failures

    - #### addBodyPart

          public void addBodyPart(BodyPart part,
                         int index)
                           throws MessagingException

      Adds a BodyPart at position `index`. If `index` is not the last one in the list, the subsequent parts are shifted up. If `index` is larger than the number of parts present, the BodyPart is appended to the end.
      Overrides:
        `addBodyPart` in class `Multipart`
      Parameters:
        `part` - The BodyPart to be inserted
        `index` - Location where to insert the part
      Throws:
        `IllegalWriteException` - if the underlying implementation does not support modification of existing values
        `MessagingException` - for other failures

    - #### isComplete

          public boolean isComplete()
                             throws MessagingException

      Return true if the final boundary line for this multipart was seen. When parsing multipart content, this class will (by default) terminate parsing with no error if the end of input is reached before seeing the final multipart boundary line. In such a case, this method will return false. (If the System property "mail.mime.multipart.ignoremissingendboundary" is set to false, parsing such a message will instead throw a MessagingException.)
      Returns:
        true if the final boundary line was seen
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4

    - #### getPreamble

          public String getPreamble()
                             throws MessagingException

      Get the preamble text, if any, that appears before the first body part of this multipart. Some protocols, such as IMAP, will not allow access to the preamble text.
      Returns:
        the preamble text, or null if no preamble
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4

    - #### setPreamble

          public void setPreamble(String preamble)
                           throws MessagingException

      Set the preamble text to be included before the first body part. Applications should generally not include any preamble text. In some cases it may be helpful to include preamble text with instructions for users of pre-MIME software. The preamble text should be complete lines, including newlines.
      Parameters:
        `preamble` - the preamble text
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.4

    - #### updateHeaders

          protected void updateHeaders()
                                throws MessagingException

      Update headers. The default implementation here just calls the `updateHeaders` method on each of its children BodyParts.

      Note that the boundary parameter is already set up when a new and empty MimeMultipart object is created.

      This method is called when the `saveChanges` method is invoked on the Message object containing this Multipart. This is typically done as part of the Message send process, however note that a client is free to call it any number of times. So if the header updating process is expensive for a specific MimeMultipart subclass, then it might itself want to track whether its internal state actually did change, and do the header updating only if necessary.

      Throws:
        `MessagingException` - for failures

    - #### writeTo

          public void writeTo(OutputStream os)
                       throws IOException,
                              MessagingException

      Iterates through all the parts and outputs each MIME part separated by a boundary.
      Specified by:
        `writeTo` in class `Multipart`
      Parameters:
        `os` - the stream to write to
      Throws:
        `IOException` - if an IO related exception occurs
        `MessagingException` - for other failures

    - #### parse

          protected void parse()
                        throws MessagingException

      Parse the InputStream from our DataSource, constructing the appropriate MimeBodyParts. The `parsed` flag is set to true, and if true on entry nothing is done. This method is called by all other methods that need data for the body parts, to make sure the data has been parsed. The `initializeProperties()` method is called before parsing the data.
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.2

    - #### createInternetHeaders

          protected InternetHeaders createInternetHeaders(InputStream is)
                                                   throws MessagingException

      Create and return an InternetHeaders object that loads the headers from the given InputStream. Subclasses can override this method to return a subclass of InternetHeaders, if necessary. This implementation simply constructs and returns an InternetHeaders object.
      Parameters:
        `is` - the InputStream to read the headers from
      Returns:
        an InternetHeaders object
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.2

    - #### createMimeBodyPart

          protected MimeBodyPart createMimeBodyPart(InternetHeaders headers,
                                        byte[] content)
                                             throws MessagingException

      Create and return a MimeBodyPart object to represent a body part parsed from the InputStream. Subclasses can override this method to return a subclass of MimeBodyPart, if necessary. This implementation simply constructs and returns a MimeBodyPart object.
      Parameters:
        `headers` - the headers for the body part
        `content` - the content of the body part
      Returns:
        a MimeBodyPart
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.2

    - #### createMimeBodyPart

          protected MimeBodyPart createMimeBodyPart(InputStream is)
                                             throws MessagingException

      Create and return a MimeBodyPart object to represent a body part parsed from the InputStream. Subclasses can override this method to return a subclass of MimeBodyPart, if necessary. This implementation simply constructs and returns a MimeBodyPart object.
      Parameters:
        `is` - InputStream containing the body part
      Returns:
        a MimeBodyPart
      Throws:
        `MessagingException` - for failures
      Since:
        JavaMail 1.2

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.