All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.mail.Part Maven / Gradle / Ivy

There is a newer version: 1.6.2
Show newest version
/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 1997-2013 Oracle and/or its affiliates. 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_1_1.html
 * or packager/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 packager/legal/LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [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.
 */

package javax.mail;

import java.io.*;
import java.util.Enumeration;
import javax.activation.DataHandler;

/**
 * The Part interface is the common base interface for 
 * Messages and BodyParts. 

* * Part consists of a set of attributes and a "Content".

* * Attributes:

* * 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.

* * Content:

* * The data type of the "content" is returned by * the getContentType() method. The MIME typing system * is used to name data types.

* * The "content" of a Part is available in various formats: *

    *
  • As a DataHandler - using the getDataHandler() method. * The "content" of a Part is also available through a * javax.activation.DataHandler object. The DataHandler * object allows clients to discover the operations available on the * content, and to instantiate the appropriate component to perform * those operations. * *
  • As an input stream - using the getInputStream() method. * Any mail-specific encodings are decoded before this stream is returned. * *
  • As a Java object - using the getContent() 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, getContent() on a * "multipart" type Part will always return a Multipart (or subclass) object. *
* * Part provides the writeTo() 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.

* * 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.

* * 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 for failures */ 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 for failures */ 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.

* * The MIME typing system is used to name Content-types. * * @return The ContentType of this part * @exception MessagingException for failures * @see javax.activation.DataHandler */ public String getContentType() throws MessagingException; /** * Is this Part of the specified MIME type? This method * compares only the primaryType and * subType. * The parameters of the content types are ignored.

* * For example, this method will return true when * comparing a Part of content type "text/plain" * with "text/plain; charset=foobar".

* * If the subType of mimeType is the * special character '*', then the subtype is ignored during the * comparison. * * @param mimeType the MIME type to test * @return true if this part is of the specified type * @exception MessagingException for failures */ 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: *

     * String disp = part.getDisposition();
     * if (disp == null || disp.equalsIgnoreCase(Part.ATTACHMENT))
     *	// treat as attachment if not first part
     * 
* * @return disposition of this part, or null if unknown * @exception MessagingException for failures * @see #ATTACHMENT * @see #INLINE * @see #getFileName */ public String getDisposition() throws MessagingException; /** * Set the disposition of this part. * * @param disposition disposition of this part * @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 * @exception MessagingException for other failures * @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 for failures */ 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 IllegalWriteException if the underlying implementation * does not support modification of this header * @exception IllegalStateException if this Part is obtained * from a READ_ONLY folder * @exception MessagingException for other failures */ 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. * * @return Filename to associate with this part * @exception MessagingException for failures */ public String getFileName() throws MessagingException; /** * Set 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. * * @param filename Filename to associate with this part * @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 * @exception MessagingException for other failures */ public void setFileName(String filename) throws MessagingException; /** * Return an input stream for this part's "content". Any * mail-specific transfer encodings will be decoded before the * input stream is provided.

* * This is typically a convenience method that just invokes * the DataHandler's getInputStream() method. * * @return an InputStream * @exception IOException this is typically thrown by the * DataHandler. Refer to the documentation for * javax.activation.DataHandler for more details. * @exception MessagingException for other failures * @see #getDataHandler * @see javax.activation.DataHandler#getInputStream */ public InputStream getInputStream() throws IOException, MessagingException; /** * Return a DataHandler for the content within this part. The * DataHandler allows clients to operate on as well as retrieve * the content. * * @return DataHandler for the content * @exception MessagingException for failures */ public DataHandler getDataHandler() throws MessagingException; /** * Return the content as a Java object. The type of the returned * object is of course dependent on the content itself. For example, * the object returned for "text/plain" content is usually a String * object. The object returned for a "multipart" content is always a * Multipart subclass. For content-types that are unknown to the * DataHandler system, an input stream is returned as the content

* * This is a convenience method that just invokes the DataHandler's * getContent() method * * @return Object * @exception IOException this is typically thrown by the * DataHandler. Refer to the documentation for * javax.activation.DataHandler for more details. * @exception MessagingException for other failures * * @see javax.activation.DataHandler#getContent */ public Object getContent() throws IOException, MessagingException; /** * This method provides the mechanism to set this part's content. * The DataHandler wraps around the actual content. * * @param dh The DataHandler for the content. * @exception IllegalWriteException if the underlying implementation * does not support modification of existing values * @exception IllegalStateException if this Part is obtained * from a READ_ONLY folder * @exception MessagingException for other failures */ public void setDataHandler(DataHandler dh) throws MessagingException; /** * A convenience method for setting this part's content. The part * internally wraps the content in a DataHandler.

* * Note that a DataContentHandler class for the specified type should * be available to the JavaMail implementation for this to work right. * i.e., to do setContent(foobar, "application/x-foobar"), * a DataContentHandler for "application/x-foobar" should be installed. * Refer to the Java Activation Framework for more information. * * @param obj A java object. * @param type MIME type of this object. * @exception IllegalWriteException if the underlying implementation * does not support modification of existing values * @exception IllegalStateException if this Part is obtained * from a READ_ONLY folder * @exception MessagingException for other failures */ public void setContent(Object obj, String type) throws MessagingException; /** * A convenience method that sets the given String as this * part's content with a MIME type of "text/plain". * * @param text The text that is the Message's content. * @exception IllegalWriteException if the underlying * implementation does not support modification of * existing values * @exception IllegalStateException if this Part is obtained * from a READ_ONLY folder * @exception MessagingException for other failures */ public void setText(String text) throws MessagingException; /** * This method sets the given Multipart object as this message's * content. * * @param mp The multipart object that is the Message's content * @exception IllegalWriteException if the underlying * implementation does not support modification of * existing values * @exception IllegalStateException if this Part is obtained * from a READ_ONLY folder * @exception MessagingException for other failures */ public void setContent(Multipart mp) throws MessagingException; /** * Output a bytestream for this Part. This bytestream is * typically an aggregration of the Part attributes and * an appropriately encoded bytestream from its 'content'.

* * Classes that implement the Part interface decide on * the appropriate encoding algorithm to be used.

* * The bytestream is typically used for sending. * * @param os the stream to write to * @exception IOException if an error occurs writing to the * stream or if an error is generated * by the javax.activation layer. * @exception MessagingException if an error occurs fetching the * data to be written * * @see javax.activation.DataHandler#writeTo */ public void writeTo(OutputStream os) throws IOException, MessagingException; /** * Get all the headers for this header name. Returns null * if no headers for this header name are available. * * @param header_name the name of this header * @return the value fields for all headers with * this name * @exception MessagingException for failures */ public String[] getHeader(String header_name) throws MessagingException; /** * Set the value for this header_name. Replaces all existing * header values with this new value. * * @param header_name the name of this header * @param header_value the value for this header * @exception IllegalWriteException if the underlying * implementation does not support modification * of existing values * @exception IllegalStateException if this Part is * obtained from a READ_ONLY folder * @exception MessagingException for other failures */ public void setHeader(String header_name, String header_value) throws MessagingException; /** * Add this value to the existing values for this header_name. * * @param header_name the name of this header * @param header_value the value for this header * @exception IllegalWriteException if the underlying * implementation does not support modification * of existing values * @exception IllegalStateException if this Part is * obtained from a READ_ONLY folder * @exception MessagingException for other failures */ public void addHeader(String header_name, String header_value) throws MessagingException; /** * Remove all headers with this name. * * @param header_name the name of this header * @exception IllegalWriteException if the underlying * implementation does not support modification * of existing values * @exception IllegalStateException if this Part is * obtained from a READ_ONLY folder * @exception MessagingException for other failures */ public void removeHeader(String header_name) throws MessagingException; /** * Return all the headers from this part as an Enumeration of * Header objects. * * @return enumeration of Header objects * @exception MessagingException for failures */ public Enumeration getAllHeaders() throws MessagingException; /** * Return matching headers from this part as an Enumeration of * Header objects. * * @param header_names the headers to match * @return enumeration of Header objects * @exception MessagingException for failures */ public Enumeration getMatchingHeaders(String[] header_names) throws MessagingException; /** * Return non-matching headers from this envelope as an Enumeration * of Header objects. * * @param header_names the headers to not match * @return enumeration of Header objects * @exception MessagingException for failures */ public Enumeration getNonMatchingHeaders(String[] header_names) throws MessagingException; }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy