1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19
20 package javax.mail;
21
22 import java.io.IOException;
23 import java.io.InputStream;
24 import java.io.OutputStream;
25 import java.util.Enumeration;
26 import javax.activation.DataHandler;
27
28 /**
29 * Note: Parts are used in Collections so implementing classes must provide
30 * a suitable implementation of equals and hashCode.
31 *
32 * @version $Rev: 578802 $ $Date: 2007-09-24 09:16:44 -0400 (Mon, 24 Sep 2007) $
33 */
34 public interface Part {
35 /**
36 * This part should be presented as an attachment.
37 */
38 public static final String ATTACHMENT = "attachment";
39 /**
40 * This part should be presented or rendered inline.
41 */
42 public static final String INLINE = "inline";
43
44 /**
45 * Add this value to the existing headers with the given name. This method
46 * does not replace any headers that may already exist.
47 *
48 * @param name The name of the target header.
49 * @param value The value to be added to the header set.
50 *
51 * @exception MessagingException
52 */
53 public abstract void addHeader(String name, String value) throws MessagingException;
54
55 /**
56 * Return all headers as an Enumeration of Header objects.
57 *
58 * @return An Enumeration containing all of the current Header objects.
59 * @exception MessagingException
60 */
61 public abstract Enumeration getAllHeaders() throws MessagingException;
62
63 /**
64 * Return a content object for this Part. The
65 * content object type is dependent upon the
66 * DataHandler for the Part.
67 *
68 * @return A content object for this Part.
69 * @exception IOException
70 * @exception MessagingException
71 */
72 public abstract Object getContent() throws IOException, MessagingException;
73
74 /**
75 * Get the ContentType for this part, or null if the
76 * ContentType has not been set. The ContentType
77 * is expressed using the MIME typing system.
78 *
79 * @return The ContentType for this part.
80 * @exception MessagingException
81 */
82 public abstract String getContentType() throws MessagingException;
83
84 /**
85 * Returns a DataHandler instance for the content
86 * with in the Part.
87 *
88 * @return A DataHandler appropriate for the Part content.
89 * @exception MessagingException
90 */
91 public abstract DataHandler getDataHandler() throws MessagingException;
92
93 /**
94 * Returns a description string for this Part. Returns
95 * null if a description has not been set.
96 *
97 * @return The description string.
98 * @exception MessagingException
99 */
100 public abstract String getDescription() throws MessagingException;
101
102 /**
103 * Return the disposition of the part. The disposition
104 * determines how the part should be presented to the
105 * user. Two common disposition values are ATTACHMENT
106 * and INLINE.
107 *
108 * @return The current disposition value.
109 * @exception MessagingException
110 */
111 public abstract String getDisposition() throws MessagingException;
112
113 /**
114 * Get a file name associated with this part. The
115 * file name is useful for presenting attachment
116 * parts as their original source. The file names
117 * are generally simple names without containing
118 * any directory information. Returns null if the
119 * filename has not been set.
120 *
121 * @return The string filename, if any.
122 * @exception MessagingException
123 */
124 public abstract String getFileName() throws MessagingException;
125
126 /**
127 * Get all Headers for this header name. Returns null if no headers with
128 * the given name exist.
129 *
130 * @param name The target header name.
131 *
132 * @return An array of all matching header values, or null if the given header
133 * does not exist.
134 * @exception MessagingException
135 */
136 public abstract String[] getHeader(String name) throws MessagingException;
137
138 /**
139 * Return an InputStream for accessing the Part
140 * content. Any mail-related transfer encodings
141 * will be removed, so the data presented with
142 * be the actual part content.
143 *
144 * @return An InputStream for accessing the part content.
145 * @exception IOException
146 * @exception MessagingException
147 */
148 public abstract InputStream getInputStream() throws IOException, MessagingException;
149
150 /**
151 * Return the number of lines in the content, or
152 * -1 if the line count cannot be determined.
153 *
154 * @return The estimated number of lines in the content.
155 * @exception MessagingException
156 */
157 public abstract int getLineCount() throws MessagingException;
158
159 /**
160 * Return all headers that match the list of names as an Enumeration of
161 * Header objects.
162 *
163 * @param names An array of names of the desired headers.
164 *
165 * @return An Enumeration of Header objects containing the matching headers.
166 * @exception MessagingException
167 */
168 public abstract Enumeration getMatchingHeaders(String[] names) throws MessagingException;
169
170 /**
171 * Return an Enumeration of all Headers except those that match the names
172 * given in the exclusion list.
173 *
174 * @param names An array of String header names that will be excluded from the return
175 * Enumeration set.
176 *
177 * @return An Enumeration of Headers containing all headers except for those named
178 * in the exclusion list.
179 * @exception MessagingException
180 */
181 public abstract Enumeration getNonMatchingHeaders(String[] names) throws MessagingException;
182
183 /**
184 * Return the size of this part, or -1 if the size
185 * cannot be reliably determined.
186 *
187 * Note: the returned size does not take into account
188 * internal encodings, nor is it an estimate of
189 * how many bytes are required to transfer this
190 * part across a network. This value is intended
191 * to give email clients a rough idea of the amount
192 * of space that might be required to present the
193 * item.
194 *
195 * @return The estimated part size, or -1 if the size
196 * information cannot be determined.
197 * @exception MessagingException
198 */
199 public abstract int getSize() throws MessagingException;
200
201 /**
202 * Tests if the part is of the specified MIME type.
203 * Only the primaryPart and subPart of the MIME
204 * type are used for the comparison; arguments are
205 * ignored. The wildcard value of "*" may be used
206 * to match all subTypes.
207 *
208 * @param mimeType The target MIME type.
209 *
210 * @return true if the part matches the input MIME type,
211 * false if it is not of the requested type.
212 * @exception MessagingException
213 */
214 public abstract boolean isMimeType(String mimeType) throws MessagingException;
215
216 /**
217 * Remove all headers with the given name from the Part.
218 *
219 * @param name The target header name used for removal.
220 *
221 * @exception MessagingException
222 */
223 public abstract void removeHeader(String name) throws MessagingException;
224
225 public abstract void setContent(Multipart content) throws MessagingException;
226
227 /**
228 * Set a content object for this part. Internally,
229 * the Part will use the MIME type encoded in the
230 * type argument to wrap the provided content object.
231 * In order for this to work properly, an appropriate
232 * DataHandler must be installed in the Java Activation
233 * Framework.
234 *
235 * @param content The content object.
236 * @param type The MIME type for the inserted content Object.
237 *
238 * @exception MessagingException
239 */
240 public abstract void setContent(Object content, String type) throws MessagingException;
241
242 /**
243 * Set a DataHandler for this part that defines the
244 * Part content. The DataHandler is used to access
245 * all Part content.
246 *
247 * @param handler The DataHandler instance.
248 *
249 * @exception MessagingException
250 */
251 public abstract void setDataHandler(DataHandler handler) throws MessagingException;
252
253 /**
254 * Set a descriptive string for this part.
255 *
256 * @param description
257 * The new description.
258 *
259 * @exception MessagingException
260 */
261 public abstract void setDescription(String description) throws MessagingException;
262
263 /**
264 * Set the disposition for this Part.
265 *
266 * @param disposition
267 * The disposition string.
268 *
269 * @exception MessagingException
270 */
271 public abstract void setDisposition(String disposition) throws MessagingException;
272
273 /**
274 * Set a descriptive file name for this part. The
275 * name should be a simple name that does not include
276 * directory information.
277 *
278 * @param name The new name value.
279 *
280 * @exception MessagingException
281 */
282 public abstract void setFileName(String name) throws MessagingException;
283
284 /**
285 * Sets a value for the given header. This operation will replace all
286 * existing headers with the given name.
287 *
288 * @param name The name of the target header.
289 * @param value The new value for the indicated header.
290 *
291 * @exception MessagingException
292 */
293 public abstract void setHeader(String name, String value) throws MessagingException;
294
295 /**
296 * Set the Part content as text. This is a convenience method that sets
297 * the content to a MIME type of "text/plain".
298 *
299 * @param content The new text content, as a String object.
300 *
301 * @exception MessagingException
302 */
303 public abstract void setText(String content) throws MessagingException;
304
305 /**
306 * Write the Part content out to the provided OutputStream as a byte
307 * stream using an encoding appropriate to the Part content.
308 *
309 * @param out The target OutputStream.
310 *
311 * @exception IOException
312 * @exception MessagingException
313 */
314 public abstract void writeTo(OutputStream out) throws IOException, MessagingException;
315 }