Part


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