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