001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 */
019
020 package javax.mail;
021
022 import java.io.IOException;
023 import java.io.InputStream;
024 import java.io.OutputStream;
025 import java.util.Enumeration;
026 import javax.activation.DataHandler;
027
028 /**
029 * Note: Parts are used in Collections so implementing classes must provide
030 * a suitable implementation of equals and hashCode.
031 *
032 * @version $Rev: 578802 $ $Date: 2007-09-24 09:16:44 -0400 (Mon, 24 Sep 2007) $
033 */
034 public interface Part {
035 /**
036 * This part should be presented as an attachment.
037 */
038 public static final String ATTACHMENT = "attachment";
039 /**
040 * This part should be presented or rendered inline.
041 */
042 public static final String INLINE = "inline";
043
044 /**
045 * Add this value to the existing headers with the given name. This method
046 * does not replace any headers that may already exist.
047 *
048 * @param name The name of the target header.
049 * @param value The value to be added to the header set.
050 *
051 * @exception MessagingException
052 */
053 public abstract void addHeader(String name, String value) throws MessagingException;
054
055 /**
056 * Return all headers as an Enumeration of Header objects.
057 *
058 * @return An Enumeration containing all of the current Header objects.
059 * @exception MessagingException
060 */
061 public abstract Enumeration getAllHeaders() throws MessagingException;
062
063 /**
064 * Return a content object for this Part. The
065 * content object type is dependent upon the
066 * DataHandler for the Part.
067 *
068 * @return A content object for this Part.
069 * @exception IOException
070 * @exception MessagingException
071 */
072 public abstract Object getContent() throws IOException, MessagingException;
073
074 /**
075 * Get the ContentType for this part, or null if the
076 * ContentType has not been set. The ContentType
077 * is expressed using the MIME typing system.
078 *
079 * @return The ContentType for this part.
080 * @exception MessagingException
081 */
082 public abstract String getContentType() throws MessagingException;
083
084 /**
085 * Returns a DataHandler instance for the content
086 * with in the Part.
087 *
088 * @return A DataHandler appropriate for the Part content.
089 * @exception MessagingException
090 */
091 public abstract DataHandler getDataHandler() throws MessagingException;
092
093 /**
094 * Returns a description string for this Part. Returns
095 * null if a description has not been set.
096 *
097 * @return The description string.
098 * @exception MessagingException
099 */
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 }