KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > mail > internet > MimePart


1 /*
2  * The contents of this file are subject to the terms
3  * of the Common Development and Distribution License
4  * (the "License"). You may not use this file except
5  * in compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * glassfish/bootstrap/legal/CDDLv1.0.txt or
9  * https://glassfish.dev.java.net/public/CDDLv1.0.html.
10  * See the License for the specific language governing
11  * permissions and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL
14  * HEADER in each file and include the License file at
15  * glassfish/bootstrap/legal/CDDLv1.0.txt. If applicable,
16  * add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your
18  * own identifying information: Portions Copyright [yyyy]
19  * [name of copyright owner]
20  */
21
22 /*
23  * @(#)MimePart.java 1.16 05/08/29
24  *
25  * Copyright 1997-2005 Sun Microsystems, Inc. All Rights Reserved.
26  */
27
28 package javax.mail.internet;
29
30 import javax.mail.*;
31 import java.io.*;
32 import java.util.Enumeration JavaDoc;
33
34 /**
35  * The MimePart interface models an <strong>Entity</strong> as defined
36  * by MIME (RFC2045, Section 2.4). <p>
37  *
38  * MimePart extends the Part interface to add additional RFC822 and MIME
39  * specific semantics and attributes. It provides the base interface for
40  * the MimeMessage and MimeBodyPart classes
41  *
42  * <hr> <strong>A note on RFC822 and MIME headers</strong><p>
43  *
44  * RFC822 and MIME header fields <strong>must</strong> contain only
45  * US-ASCII characters. If a header contains non US-ASCII characters,
46  * it must be encoded as per the rules in RFC 2047. The MimeUtility
47  * class provided in this package can be used to to achieve this.
48  * Callers of the <code>setHeader</code>, <code>addHeader</code>, and
49  * <code>addHeaderLine</code> methods are responsible for enforcing
50  * the MIME requirements for the specified headers. In addition, these
51  * header fields must be folded (wrapped) before being sent if they
52  * exceed the line length limitation for the transport (1000 bytes for
53  * SMTP). Received headers may have been folded. The application is
54  * responsible for folding and unfolding headers as appropriate. <p>
55  *
56  * @see MimeUtility
57  * @see javax.mail.Part
58  * @author John Mani
59  */
60
61 public interface MimePart extends Part {
62
63     /**
64      * Get the values of all header fields available for this header,
65      * returned as a single String, with the values separated by the
66      * delimiter. If the delimiter is <code>null</code>, only the
67      * first value is returned.
68      *
69      * @param name the name of this header
70      * @param delimiter delimiter between fields in returned string
71      * @return the value fields for all headers with
72      * this name
73      * @exception MessagingException
74      */
75     public String JavaDoc getHeader(String JavaDoc name, String JavaDoc delimiter)
76                 throws MessagingException;
77
78     /**
79      * Add a raw RFC822 header-line.
80      * @exception IllegalWriteException if the underlying
81      * implementation does not support modification
82      * @exception IllegalStateException if this Part is
83      * obtained from a READ_ONLY folder
84      */
85     public void addHeaderLine(String JavaDoc line) throws MessagingException;
86
87     /**
88      * Get all header lines as an Enumeration of Strings. A Header
89      * line is a raw RFC822 header-line, containing both the "name"
90      * and "value" field.
91      */
92     public Enumeration JavaDoc getAllHeaderLines() throws MessagingException;
93
94     /**
95      * Get matching header lines as an Enumeration of Strings.
96      * A Header line is a raw RFC822 header-line, containing both
97      * the "name" and "value" field.
98      */
99     public Enumeration JavaDoc getMatchingHeaderLines(String JavaDoc[] names)
100             throws MessagingException;
101
102     /**
103      * Get non-matching header lines as an Enumeration of Strings.
104      * A Header line is a raw RFC822 header-line, containing both
105      * the "name" and "value" field.
106      */
107     public Enumeration JavaDoc getNonMatchingHeaderLines(String JavaDoc[] names)
108             throws MessagingException;
109
110     /**
111      * Get the transfer encoding of this part.
112      *
113      * @return content-transfer-encoding
114      * @exception MessagingException
115      */
116     public String JavaDoc getEncoding() throws MessagingException;
117
118     /**
119      * Get the Content-ID of this part. Returns null if none present.
120      *
121      * @return content-ID
122      */
123     public String JavaDoc getContentID() throws MessagingException;
124
125     /**
126      * Get the Content-MD5 digest of this part. Returns null if
127      * none present.
128      *
129      * @return content-MD5
130      */
131     public String JavaDoc getContentMD5() throws MessagingException;
132
133     /**
134      * Set the Content-MD5 of this part.
135      *
136      * @param md5 the MD5 value
137      * @exception IllegalWriteException if the underlying
138      * implementation does not support modification
139      * @exception IllegalStateException if this Part is
140      * obtained from a READ_ONLY folder
141      */
142     public void setContentMD5(String JavaDoc md5) throws MessagingException;
143
144     /**
145      * Get the language tags specified in the Content-Language header
146      * of this MimePart. The Content-Language header is defined by
147      * RFC 1766. Returns <code>null</code> if this header is not
148      * available.
149      */
150     public String JavaDoc[] getContentLanguage() throws MessagingException;
151
152     /**
153      * Set the Content-Language header of this MimePart. The
154      * Content-Language header is defined by RFC1766.
155      *
156      * @param languages array of language tags
157      * @exception IllegalWriteException if the underlying
158      * implementation does not support modification
159      * @exception IllegalStateException if this Part is
160      * obtained from a READ_ONLY folder
161      */
162     public void setContentLanguage(String JavaDoc[] languages)
163             throws MessagingException;
164     
165     /**
166      * Convenience method that sets the given String as this
167      * part's content, with a MIME type of "text/plain". If the
168      * string contains non US-ASCII characters. it will be encoded
169      * using the platform's default charset. The charset is also
170      * used to set the "charset" parameter. <p>
171      *
172      * Note that there may be a performance penalty if
173      * <code>text</code> is large, since this method may have
174      * to scan all the characters to determine what charset to
175      * use. <p>
176      *
177      * If the charset is already known, use the
178      * <code>setText</code> method that takes the charset parameter.
179      *
180      * @param text the text content to set
181      * @exception MessagingException if an error occurs
182      * @see #setText(String text, String charset)
183      */
184     public void setText(String JavaDoc text) throws MessagingException;
185
186     /**
187      * Convenience method that sets the given String as this part's
188      * content, with a MIME type of "text/plain" and the specified
189      * charset. The given Unicode string will be charset-encoded
190      * using the specified charset. The charset is also used to set
191      * "charset" parameter.
192      *
193      * @param text the text content to set
194      * @param charset the charset to use for the text
195      * @exception MessagingException if an error occurs
196      */
197     public void setText(String JavaDoc text, String JavaDoc charset)
198             throws MessagingException;
199
200     /**
201      * Convenience method that sets the given String as this part's
202      * content, with a primary MIME type of "text" and the specified
203      * MIME subtype. The given Unicode string will be charset-encoded
204      * using the specified charset. The charset is also used to set
205      * the "charset" parameter.
206      *
207      * @param text the text content to set
208      * @param charset the charset to use for the text
209      * @param subtype the MIME subtype to use (e.g., "html")
210      * @exception MessagingException if an error occurs
211      * @since JavaMail 1.4
212      */
213     public void setText(String JavaDoc text, String JavaDoc charset, String JavaDoc subtype)
214                         throws MessagingException;
215 }
216
Popular Tags