/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved. * * The contents of this file are subject to the terms of either the GNU * General Public License Version 2 only ("GPL") or the Common Development * and Distribution License("CDDL") (collectively, the "License").  You * may not use this file except in compliance with the License. You can obtain * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html * or glassfish/bootstrap/legal/LICENSE.txt.  See the License for the specific * language governing permissions and limitations under the License. * * When distributing the software, include this License Header Notice in each * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt. * Sun designates this particular file as subject to the "Classpath" exception * as provided by Sun in the GPL Version 2 section of the License file that * accompanied this code.  If applicable, add the following below the License * Header, with the fields enclosed by brackets [] replaced by your own * identifying information: "Portions Copyrighted [year] * [name of copyright owner]" * * Contributor(s): * * If you wish your version of this file to be governed by only the CDDL or * only the GPL Version 2, indicate your decision by adding "[Contributor] * elects to include this software in this distribution under the [CDDL or GPL * Version 2] license."  If you don't indicate a single choice of license, a * recipient has the option to distribute your version of this file under * either the CDDL, the GPL Version 2 or to extend the choice of license to * its licensees as provided above.  However, if you add GPL Version 2 code * and therefore, elected the GPL Version 2 license, then the option applies * only if the new code is made subject to such option by the copyright * holder. *//* * @(#)Part.java	1.21 07/05/04 */package javax.mail;import java.io.*;import java.util.Enumeration;import javax.activation.DataHandler;/** * The <code>Part</code> interface is the common base interface for  * Messages and BodyParts. <p> * * Part consists of a set of attributes and a "Content".<p> * * <strong> Attributes: </strong> <p> * * The JavaMail API defines a set of standard Part attributes that are * considered to be common to most existing Mail systems. These * attributes have their own settor and gettor methods. Mail systems  * may support other Part attributes as well, these are represented as  * name-value pairs where both the name and value are Strings.<p> * * <strong> Content: </strong> <p> * * The <strong>data type</strong> of the "content" is returned by * the <code>getContentType()</code> method. The MIME typing system * is used to name data types. <p> * * The "content" of a Part is available in various formats: * <ul> * <li> As a DataHandler - using the <code>getDataHandler()</code> method. * The "content" of a Part is also available through a  * <code>javax.activation.DataHandler</code> object. The DataHandler  * object allows clients to discover the operations available on the * content, and to instantiate the appropriate component to perform * those operations.  * * <li> As an input stream - using the <code>getInputStream()</code> method. * Any mail-specific encodings are decoded before this stream is returned. * * <li> As a Java object - using the <code>getContent()</code> method. * This method returns the "content" as a Java object. * The returned object is of course dependent on the content * itself. In particular, a "multipart" Part's content is always a  * Multipart or subclass thereof.  That is, <code>getContent()</code> on a  * "multipart" type Part will always return a Multipart (or subclass) object. * </ul> * * Part provides the <code>writeTo()</code> method that streams * out its bytestream in mail-safe form suitable for transmission.  * This bytestream is typically an aggregation of the Part attributes * and its content's bytestream. <p> * * Message and BodyPart implement the Part interface. Note that in * MIME parlance, Part models an Entity (RFC 2045, Section 2.4). * * @author John Mani */public interface Part {    /**     * Return the size of the content of this part in bytes.     * Return -1 if the size cannot be determined. <p>     *     * Note that the size may not be an exact measure of the content     * size and may or may not account for any transfer encoding     * of the content. The size is appropriate for display in a      * user interface to give the user a rough idea of the size     * of this part.     *     * @return		size of content in bytes     * @exception	MessagingException     */    public int getSize() throws MessagingException;    /**     * Return the number of lines in the content of this part.      * Return -1 if the number cannot be determined.     *     * Note that this number may not be an exact measure of the      * content length and may or may not account for any transfer      * encoding of the content.      *     * @return		number of lines in the content.     * @exception	MessagingException     */    public int getLineCount() throws MessagingException;    /**     * Returns the Content-Type of the content of this part.     * Returns null if the Content-Type could not be determined. <p>     *     * The MIME typing system is used to name Content-types.     *     * @return		The ContentType of this part     * @exception	MessagingException     * @see		javax.activation.DataHandler     */    public String getContentType() throws MessagingException;    /**     * Is this Part of the specified MIME type?  This method     * compares <strong>only the <code>primaryType</code> and      * <code>subType</code></strong>.     * The parameters of the content types are ignored. <p>     *     * For example, this method will return <code>true</code> when     * comparing a Part of content type <strong>"text/plain"</strong>     * with <strong>"text/plain; charset=foobar"</strong>. <p>     *     * If the <code>subType</code> of <code>mimeType</code> is the     * special character '*', then the subtype is ignored during the     * comparison.     */    public boolean isMimeType(String mimeType) throws MessagingException;    /**     * This part should be presented as an attachment.     * @see #getDisposition     * @see #setDisposition     */    public static final String ATTACHMENT = "attachment";    /**     * This part should be presented inline.     * @see #getDisposition     * @see #setDisposition     */    public static final String INLINE = "inline";    /**     * Return the disposition of this part.  The disposition     * describes how the part should be presented to the user.     * (See RFC 2183.)  The return value should be considered     * without regard to case.  For example: <p>     * <blockquote><pre>     * String disp = part.getDisposition();     * if (disp == null || disp.equalsIgnoreCase(Part.ATTACHMENT))     *	// treat as attachment if not first part     * </pre></blockquote>     *     * @return		disposition of this part, or null if unknown     * @exception	MessagingException     * @see #ATTACHMENT     * @see #INLINE     * @see #getFileName     */    public String getDisposition() throws MessagingException;    /**     * Set the disposition of this part.     *     * @param	disposition	disposition of this part     * @exception	MessagingException     * @exception	IllegalWriteException if the underlying implementation     *			does not support modification of this header     * @exception	IllegalStateException if this Part is obtained     *			from a READ_ONLY folder     * @see #ATTACHMENT     * @see #INLINE     * @see #setFileName     */    public void setDisposition(String disposition) throws MessagingException;    /**     * Return a description String for this part. This typically     * associates some descriptive information with this part.     * Returns null if none is available.     *     * @return		description of this part     * @exception	MessagingException     */    public String getDescription() throws MessagingException;    /**     * Set a description String for this part. This typically     * associates some descriptive information with this part.     *     * @param	description	description of this part     * @exception	MessagingException     * @exception	IllegalWriteException if the underlying implementation     *			does not support modification of this header     * @exception	IllegalStateException if this Part is obtained     *			from a READ_ONLY folder     */    public void setDescription(String description) throws MessagingException;    /**     * Get the filename associated with this part, if possible.     * Useful if this part represents an "attachment" that was     * loaded from a file.  The filename will usually be a simple     * name, not including directory components.     *