001/****************************************************************
002 * Licensed to the Apache Software Foundation (ASF) under one   *
003 * or more contributor license agreements.  See the NOTICE file *
004 * distributed with this work for additional information        *
005 * regarding copyright ownership.  The ASF licenses this file   *
006 * to you under the Apache License, Version 2.0 (the            *
007 * "License"); you may not use this file except in compliance   *
008 * with the License.  You may obtain a copy of the License at   *
009 *                                                              *
010 *   http://www.apache.org/licenses/LICENSE-2.0                 *
011 *                                                              *
012 * Unless required by applicable law or agreed to in writing,   *
013 * software distributed under the License is distributed on an  *
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
015 * KIND, either express or implied.  See the License for the    *
016 * specific language governing permissions and limitations      *
017 * under the License.                                           *
018 ****************************************************************/
019
020package org.apache.james.mime4j.dom;
021
022import java.util.List;
023
024/**
025 * A MIME multipart body (as defined in RFC 2045). A multipart body has a ordered list of
026 * body parts. The multipart body also has a preamble and epilogue. The preamble consists of
027 * whatever characters appear before the first body part while the epilogue consists of whatever
028 * characters come after the last body part.
029 */
030public interface Multipart extends Body {
031
032    /**
033     * Gets the multipart sub-type. E.g. <code>alternative</code> (the
034     * default) or <code>parallel</code>. See RFC 2045 for common sub-types
035     * and their meaning.
036     *
037     * @return the multipart sub-type.
038     */
039    String getSubType();
040
041    /**
042     * Returns the number of body parts.
043     *
044     * @return number of <code>Entity</code> objects.
045     */
046    int getCount();
047
048    /**
049     * Gets the list of body parts. The list is immutable.
050     *
051     * @return the list of <code>Entity</code> objects.
052     */
053    public List<Entity> getBodyParts();
054
055    /**
056     * Sets the list of body parts.
057     *
058     * @param bodyParts
059     *            the new list of <code>Entity</code> objects.
060     */
061    void setBodyParts(List<Entity> bodyParts);
062
063    /**
064     * Adds a body part to the end of the list of body parts.
065     *
066     * @param bodyPart
067     *            the body part.
068     */
069    void addBodyPart(Entity bodyPart);
070
071    /**
072     * Inserts a body part at the specified position in the list of body parts.
073     *
074     * @param bodyPart
075     *            the body part.
076     * @param index
077     *            index at which the specified body part is to be inserted.
078     * @throws IndexOutOfBoundsException
079     *             if the index is out of range (index &lt; 0 || index &gt;
080     *             getCount()).
081     */
082    void addBodyPart(Entity bodyPart, int index);
083
084    /**
085     * Removes the body part at the specified position in the list of body
086     * parts.
087     *
088     * @param index
089     *            index of the body part to be removed.
090     * @return the removed body part.
091     * @throws IndexOutOfBoundsException
092     *             if the index is out of range (index &lt; 0 || index &gt;=
093     *             getCount()).
094     */
095    Entity removeBodyPart(int index);
096
097    /**
098     * Replaces the body part at the specified position in the list of body
099     * parts with the specified body part.
100     *
101     * @param bodyPart
102     *            body part to be stored at the specified position.
103     * @param index
104     *            index of body part to replace.
105     * @return the replaced body part.
106     * @throws IndexOutOfBoundsException
107     *             if the index is out of range (index &lt; 0 || index &gt;=
108     *             getCount()).
109     */
110    Entity replaceBodyPart(Entity bodyPart, int index);
111
112    /**
113     * Gets the preamble or null if the message has no preamble.
114     *
115     * @return the preamble.
116     */
117    String getPreamble();
118
119    /**
120     * Sets the preamble with a value or null to remove the preamble.
121     *
122     * @param preamble
123     *            the preamble.
124     */
125    void setPreamble(String preamble);
126
127    /**
128     * Gets the epilogue or null if the message has no epilogue
129     *
130     * @return the epilogue.
131     */
132    String getEpilogue();
133
134    /**
135     * Sets the epilogue value, or remove it if the value passed is null.
136     *
137     * @param epilogue
138     *            the epilogue.
139     */
140    void setEpilogue(String epilogue);
141
142}