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 * @(#)Part.java 1.21 07/05/04
39 */
40
41 package javax.mail;
42
43 import java.io;
44 import java.util.Enumeration;
45 import javax.activation.DataHandler;
46
47 /**
48 * The <code>Part</code> interface is the common base interface for
49 * Messages and BodyParts. <p>
50 *
51 * Part consists of a set of attributes and a "Content".<p>
52 *
53 * <strong> Attributes: </strong> <p>
54 *
55 * The JavaMail API defines a set of standard Part attributes that are
56 * considered to be common to most existing Mail systems. These
57 * attributes have their own settor and gettor methods. Mail systems
58 * may support other Part attributes as well, these are represented as
59 * name-value pairs where both the name and value are Strings.<p>
60 *
61 * <strong> Content: </strong> <p>
62 *
63 * The <strong>data type</strong> of the "content" is returned by
64 * the <code>getContentType()</code> method. The MIME typing system
65 * is used to name data types. <p>
66 *
67 * The "content" of a Part is available in various formats:
68 * <ul>
69 * <li> As a DataHandler - using the <code>getDataHandler()</code> method.
70 * The "content" of a Part is also available through a
71 * <code>javax.activation.DataHandler</code> object. The DataHandler
72 * object allows clients to discover the operations available on the
73 * content, and to instantiate the appropriate component to perform
74 * those operations.
75 *
76 * <li> As an input stream - using the <code>getInputStream()</code> method.
77 * Any mail-specific encodings are decoded before this stream is returned.
78 *
79 * <li> As a Java object - using the <code>getContent()</code> method.
80 * This method returns the "content" as a Java object.
81 * The returned object is of course dependent on the content
82 * itself. In particular, a "multipart" Part's content is always a
83 * Multipart or subclass thereof. That is, <code>getContent()</code> on a
84 * "multipart" type Part will always return a Multipart (or subclass) object.
85 * </ul>
86 *
87 * Part provides the <code>writeTo()</code> method that streams
88 * out its bytestream in mail-safe form suitable for transmission.
89 * This bytestream is typically an aggregation of the Part attributes
90 * and its content's bytestream. <p>
91 *
92 * Message and BodyPart implement the Part interface. Note that in
93 * MIME parlance, Part models an Entity (RFC 2045, Section 2.4).
94 *
95 * @author John Mani
96 */
97
98 public interface Part {
99
100 /**
101 * Return the size of the content of this part in bytes.
102 * Return -1 if the size cannot be determined. <p>
103 *
104 * Note that the size may not be an exact measure of the content
105 * size and may or may not account for any transfer encoding
106 * of the content. The size is appropriate for display in a
107 * user interface to give the user a rough idea of the size
108 * of this part.
109 *
110 * @return size of content in bytes
111 * @exception MessagingException
112 */
113 public int getSize() throws MessagingException;
114
115 /**
116 * Return the number of lines in the content of this part.
117 * Return -1 if the number cannot be determined.
118 *
119 * Note that this number may not be an exact measure of the
120 * content length and may or may not account for any transfer
121 * encoding of the content.
122 *
123 * @return number of lines in the content.
124 * @exception MessagingException
125 */
126 public int getLineCount() throws MessagingException;
127
128 /**
129 * Returns the Content-Type of the content of this part.
130 * Returns null if the Content-Type could not be determined. <p>
131 *
132 * The MIME typing system is used to name Content-types.
133 *
134 * @return The ContentType of this part
135 * @exception MessagingException
136 * @see javax.activation.DataHandler
137 */
138 public String getContentType() throws MessagingException;
139
140 /**
141 * Is this Part of the specified MIME type? This method
142 * compares <strong>only the <code>primaryType</code> and
143 * <code>subType</code></strong>.
144 * The parameters of the content types are ignored. <p>
145 *
146 * For example, this method will return <code>true</code> when
147 * comparing a Part of content type <strong>"text/plain"</strong>
148 * with <strong>"text/plain; charset=foobar"</strong>. <p>
149 *
150 * If the <code>subType</code> of <code>mimeType</code> is the
151 * special character '*', then the subtype is ignored during the
152 * comparison.
153 */
154 public boolean isMimeType(String mimeType) throws MessagingException;
155
156 /**
157 * This part should be presented as an attachment.
158 * @see #getDisposition
159 * @see #setDisposition
160 */
161 public static final String ATTACHMENT = "attachment";
162
163 /**
164 * This part should be presented inline.
165 * @see #getDisposition
166 * @see #setDisposition
167 */
168 public static final String INLINE = "inline";
169
170 /**
171 * Return the disposition of this part. The disposition
172 * describes how the part should be presented to the user.
173 * (See RFC 2183.) The return value should be considered
174 * without regard to case. For example: <p>
175 * <blockquote><pre>
176 * String disp = part.getDisposition();
177 * if (disp == null || disp.equalsIgnoreCase(Part.ATTACHMENT))
178 * // treat as attachment if not first part
179 * </pre></blockquote>
180 *
181 * @return disposition of this part, or null if unknown
182 * @exception MessagingException
183 * @see #ATTACHMENT
184 * @see #INLINE
185 * @see #getFileName
186 */
187 public String getDisposition() throws MessagingException;
188
189 /**
190 * Set the disposition of this part.
191 *
192 * @param disposition disposition of this part
193 * @exception MessagingException
194 * @exception IllegalWriteException if the underlying implementation
195 * does not support modification of this header
196 * @exception IllegalStateException if this Part is obtained
197 * from a READ_ONLY folder
198 * @see #ATTACHMENT
199 * @see #INLINE
200 * @see #setFileName
201 */
202 public void setDisposition(String disposition) throws MessagingException;
203
204 /**
205 * Return a description String for this part. This typically
206 * associates some descriptive information with this part.
207 * Returns null if none is available.
208 *
209 * @return description of this part
210 * @exception MessagingException
211 */
212 public String getDescription() throws MessagingException;
213
214 /**
215 * Set a description String for this part. This typically
216 * associates some descriptive information with this part.
217 *
218 * @param description description of this part
219 * @exception MessagingException
220 * @exception IllegalWriteException if the underlying implementation
221 * does not support modification of this header
222 * @exception IllegalStateException if this Part is obtained
223 * from a READ_ONLY folder
224 */
225 public void setDescription(String description) throws MessagingException;
226
227 /**
228 * Get the filename associated with this part, if possible.
229 * Useful if this part represents an "attachment" that was
230 * loaded from a file. The filename will usually be a simple
231 * name, not including directory components.
232 *
233 * @return Filename to associate with this part
234 */
235 public String getFileName() throws MessagingException;
236
237 /**
238 * Set the filename associated with this part, if possible.
239 * Useful if this part represents an "attachment" that was
240 * loaded from a file. The filename will usually be a simple
241 * name, not including directory components.
242 *
243 * @param filename Filename to associate with this part
244 * @exception IllegalWriteException if the underlying implementation
245 * does not support modification of this header
246 * @exception IllegalStateException if this Part is obtained
247 * from a READ_ONLY folder
248 */
249 public void setFileName(String filename) throws MessagingException;
250
251 /**
252 * Return an input stream for this part's "content". Any
253 * mail-specific transfer encodings will be decoded before the
254 * input stream is provided. <p>
255 *
256 * This is typically a convenience method that just invokes
257 * the DataHandler's <code>getInputStream()</code> method.
258 *
259 * @return an InputStream
260 * @exception IOException this is typically thrown by the
261 * DataHandler. Refer to the documentation for
262 * javax.activation.DataHandler for more details.
263 * @exception MessagingException
264 * @see #getDataHandler
265 * @see javax.activation.DataHandler#getInputStream
266 */
267 public InputStream getInputStream()
268 throws IOException, MessagingException;
269
270 /**
271 * Return a DataHandler for the content within this part. The
272 * DataHandler allows clients to operate on as well as retrieve
273 * the content.
274 *
275 * @return DataHandler for the content
276 * @exception MessagingException
277 */
278 public DataHandler getDataHandler() throws MessagingException;
279
280 /**
281 * Return the content as a Java object. The type of the returned
282 * object is of course dependent on the content itself. For example,
283 * the object returned for "text/plain" content is usually a String
284 * object. The object returned for a "multipart" content is always a
285 * Multipart subclass. For content-types that are unknown to the
286 * DataHandler system, an input stream is returned as the content <p>
287 *
288 * This is a convenience method that just invokes the DataHandler's
289 * getContent() method
290 *
291 * @return Object
292 * @exception MessagingException
293 * @exception IOException this is typically thrown by the
294 * DataHandler. Refer to the documentation for
295 * javax.activation.DataHandler for more details.
296 *
297 * @see javax.activation.DataHandler#getContent
298 */
299 public Object getContent() throws IOException, MessagingException;
300
301 /**
302 * This method provides the mechanism to set this part's content.
303 * The DataHandler wraps around the actual content.
304 *
305 * @param dh The DataHandler for the content.
306 * @exception MessagingException
307 * @exception IllegalWriteException if the underlying implementation
308 * does not support modification of existing values
309 * @exception IllegalStateException if this Part is obtained
310 * from a READ_ONLY folder
311 */
312 public void setDataHandler(DataHandler dh) throws MessagingException;
313
314 /**
315 * A convenience method for setting this part's content. The part
316 * internally wraps the content in a DataHandler. <p>
317 *
318 * Note that a DataContentHandler class for the specified type should
319 * be available to the JavaMail implementation for this to work right.
320 * i.e., to do <code>setContent(foobar, "application/x-foobar")</code>,
321 * a DataContentHandler for "application/x-foobar" should be installed.
322 * Refer to the Java Activation Framework for more information.
323 *
324 * @param obj A java object.
325 * @param type MIME type of this object.
326 * @exception IllegalWriteException if the underlying implementation
327 * does not support modification of existing values
328 * @exception IllegalStateException if this Part is obtained
329 * from a READ_ONLY folder
330 */
331 public void setContent(Object obj, String type)
332 throws MessagingException;
333
334 /**
335 * A convenience method that sets the given String as this
336 * part's content with a MIME type of "text/plain".
337 *
338 * @param text The text that is the Message's content.
339 * @exception IllegalWriteException if the underlying
340 * implementation does not support modification of
341 * existing values
342 * @exception IllegalStateException if this Part is obtained
343 * from a READ_ONLY folder
344 */
345 public void setText(String text) throws MessagingException;
346
347 /**
348 * This method sets the given Multipart object as this message's
349 * content.
350 *
351 * @param mp The multipart object that is the Message's content
352 * @exception IllegalWriteException if the underlying
353 * implementation does not support modification of
354 * existing values
355 * @exception IllegalStateException if this Part is obtained
356 * from a READ_ONLY folder
357 */
358 public void setContent(Multipart mp) throws MessagingException;
359
360 /**
361 * Output a bytestream for this Part. This bytestream is
362 * typically an aggregration of the Part attributes and
363 * an appropriately encoded bytestream from its 'content'. <p>
364 *
365 * Classes that implement the Part interface decide on
366 * the appropriate encoding algorithm to be used. <p>
367 *
368 * The bytestream is typically used for sending.
369 *
370 * @exception IOException if an error occurs writing to the
371 * stream or if an error is generated
372 * by the javax.activation layer.
373 * @exception MessagingException if an error occurs fetching the
374 * data to be written
375 *
376 * @see javax.activation.DataHandler#writeTo
377 */
378 public void writeTo(OutputStream os) throws IOException, MessagingException;
379
380 /**
381 * Get all the headers for this header name. Returns <code>null</code>
382 * if no headers for this header name are available.
383 *
384 * @param header_name the name of this header
385 * @return the value fields for all headers with
386 * this name
387 * @exception MessagingException
388 */
389 public String[] getHeader(String header_name)
390 throws MessagingException;
391
392 /**
393 * Set the value for this header_name. Replaces all existing
394 * header values with this new value.
395 *
396 * @param header_name the name of this header
397 * @param header_value the value for this header
398 * @exception MessagingException
399 * @exception IllegalWriteException if the underlying
400 * implementation does not support modification
401 * of existing values
402 * @exception IllegalStateException if this Part is
403 * obtained from a READ_ONLY folder
404 */
405 public void setHeader(String header_name, String header_value)
406 throws MessagingException;
407 /**
408 * Add this value to the existing values for this header_name.
409 *
410 * @param header_name the name of this header
411 * @param header_value the value for this header
412 * @exception MessagingException
413 * @exception IllegalWriteException if the underlying
414 * implementation does not support modification
415 * of existing values
416 * @exception IllegalStateException if this Part is
417 * obtained from a READ_ONLY folder
418 */
419 public void addHeader(String header_name, String header_value)
420 throws MessagingException;
421 /**
422 * Remove all headers with this name.
423 *
424 * @param header_name the name of this header
425 * @exception MessagingException
426 * @exception IllegalWriteException if the underlying
427 * implementation does not support modification
428 * of existing values
429 * @exception IllegalStateException if this Part is
430 * obtained from a READ_ONLY folder
431 */
432 public void removeHeader(String header_name)
433 throws MessagingException;
434
435 /**
436 * Return all the headers from this part as an Enumeration of
437 * Header objects.
438 *
439 * @return enumeration of Header objects
440 * @exception MessagingException
441 */
442 public Enumeration getAllHeaders() throws MessagingException;
443
444 /**
445 * Return matching headers from this part as an Enumeration of
446 * Header objects.
447 *
448 * @return enumeration of Header objects
449 * @exception MessagingException
450 */
451 public Enumeration getMatchingHeaders(String[] header_names)
452 throws MessagingException;
453
454 /**
455 * Return non-matching headers from this envelope as an Enumeration
456 * of Header objects.
457 *
458 * @return enumeration of Header objects
459 * @exception MessagingException
460 */
461 public Enumeration getNonMatchingHeaders(String[] header_names)
462 throws MessagingException;
463 }
Save This Page