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
022/**
023 * A MIME entity. An entity has a header and a body (as defined in RFC 2045).
024 */
025public interface Entity extends Disposable {
026
027    /**
028     * Gets the parent entity of this entity.
029     * Returns <code>null</code> if this is the root entity.
030     *
031     * @return the parent or <code>null</code>.
032     */
033    Entity getParent();
034
035    /**
036     * Sets the parent entity of this entity.
037     *
038     * @param parent the parent entity or <code>null</code> if
039     *        this will be the root entity.
040     */
041    void setParent(Entity parent);
042
043    /**
044     * Gets the entity header.
045     *
046     * @return the header.
047     */
048    Header getHeader();
049
050    /**
051     * Sets the entity header.
052     *
053     * @param header the header.
054     */
055    void setHeader(Header header);
056
057    /**
058     * Gets the body of this entity.
059     *
060     * @return the body,
061     */
062    Body getBody();
063
064    /**
065     * Sets the body of this entity.
066     *
067     * @param body the body.
068     * @throws IllegalStateException if the body has already been set.
069     */
070    void setBody(Body body);
071
072    /**
073     * Removes and returns the body of this entity. The removed body may be
074     * attached to another entity. If it is no longer needed it should be
075     * {@link Disposable#dispose() disposed} of.
076     *
077     * @return the removed body or <code>null</code> if no body was set.
078     */
079    Body removeBody();
080
081    /**
082     * Determines if the MIME type of this <code>Entity</code> is
083     * <code>multipart/*</code>. Since multipart-entities must have
084     * a boundary parameter in the <code>Content-Type</code> field this
085     * method returns <code>false</code> if no boundary exists.
086     *
087     * @return <code>true</code> on match, <code>false</code> otherwise.
088     */
089    boolean isMultipart();
090
091    /**
092     * Determines the MIME type of this <code>Entity</code>. The MIME type
093     * is derived by looking at the parent's Content-Type field if no
094     * Content-Type field is set for this <code>Entity</code>.
095     *
096     * @return the MIME type.
097     */
098    String getMimeType();
099
100    /**
101     * Determines the MIME character set encoding of this <code>Entity</code>.
102     *
103     * @return the MIME character set encoding.
104     */
105    String getCharset();
106
107    /**
108     * Determines the transfer encoding of this <code>Entity</code>.
109     *
110     * @return the transfer encoding.
111     */
112    String getContentTransferEncoding();
113
114    /**
115     * Return the disposition type of the content disposition of this
116     * <code>Entity</code>.
117     *
118     * @return the disposition type or <code>null</code> if no disposition
119     *         type has been set.
120     */
121    String getDispositionType();
122
123    /**
124     * Returns the filename parameter of the content disposition of this
125     * <code>Entity</code>.
126     *
127     * @return the filename parameter of the content disposition or
128     *         <code>null</code> if the filename has not been set.
129     */
130    String getFilename();
131
132}