-
Notifications
You must be signed in to change notification settings - Fork 101
/
MimePart.java
224 lines (206 loc) · 8.25 KB
/
MimePart.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
/*
* Copyright (c) 1997, 2023 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package jakarta.mail.internet;
import jakarta.mail.*;
import java.io.*;
import java.util.Enumeration;
/**
* The MimePart interface models an <strong>Entity</strong> as defined
* by MIME (RFC2045, Section 2.4). <p>
*
* MimePart extends the Part interface to add additional RFC822 and MIME
* specific semantics and attributes. It provides the base interface for
* the MimeMessage and MimeBodyPart classes
*
* <hr> <strong>A note on RFC822 and MIME headers</strong><p>
*
* RFC822 and MIME header fields <strong>must</strong> contain only
* US-ASCII characters. If a header contains non US-ASCII characters,
* it must be encoded as per the rules in RFC 2047. The MimeUtility
* class provided in this package can be used to to achieve this.
* Callers of the <code>setHeader</code>, <code>addHeader</code>, and
* <code>addHeaderLine</code> methods are responsible for enforcing
* the MIME requirements for the specified headers. In addition, these
* header fields must be folded (wrapped) before being sent if they
* exceed the line length limitation for the transport (1000 bytes for
* SMTP). Received headers may have been folded. The application is
* responsible for folding and unfolding headers as appropriate.
*
* @see MimeUtility
* @see jakarta.mail.Part
* @author John Mani
*/
public interface MimePart extends Part {
/**
* Get the values of all header fields available for this header,
* returned as a single String, with the values separated by the
* delimiter. If the delimiter is <code>null</code>, only the
* first value is returned.
*
* @param name the name of this header
* @param delimiter delimiter between fields in returned string
* @return the value fields for all headers with
* this name
* @exception MessagingException for failures
*/
public String getHeader(String name, String delimiter)
throws MessagingException;
/**
* Add a raw RFC822 header-line.
*
* @param line the line to add
* @exception IllegalWriteException if the underlying
* implementation does not support modification
* @exception IllegalStateException if this Part is
* obtained from a READ_ONLY folder
* @exception MessagingException for other failures
*/
public void addHeaderLine(String line) throws MessagingException;
/**
* Get all header lines as an Enumeration of Strings. A Header
* line is a raw RFC822 header-line, containing both the "name"
* and "value" field.
*
* @return an Enumeration of Strings
* @exception MessagingException for failures
*/
public Enumeration<String> getAllHeaderLines() throws MessagingException;
/**
* Get matching header lines as an Enumeration of Strings.
* A Header line is a raw RFC822 header-line, containing both
* the "name" and "value" field.
*
* @param names the headers to return
* @return an Enumeration of Strings
* @exception MessagingException for failures
*/
public Enumeration<String> getMatchingHeaderLines(String[] names)
throws MessagingException;
/**
* Get non-matching header lines as an Enumeration of Strings.
* A Header line is a raw RFC822 header-line, containing both
* the "name" and "value" field.
*
* @param names the headers to not return
* @return an Enumeration of Strings
* @exception MessagingException for failures
*/
public Enumeration<String> getNonMatchingHeaderLines(String[] names)
throws MessagingException;
/**
* Get the transfer encoding of this part.
*
* @return content-transfer-encoding
* @exception MessagingException for failures
*/
public String getEncoding() throws MessagingException;
/**
* Get the Content-ID of this part. Returns null if none present.
*
* @return content-ID
* @exception MessagingException for failures
*/
public String getContentID() throws MessagingException;
/**
* Get the Content-MD5 digest of this part. Returns null if
* none present.
*
* @return content-MD5
* @exception MessagingException for failures
*/
public String getContentMD5() throws MessagingException;
/**
* Set the Content-MD5 of this part.
*
* @param md5 the MD5 value
* @exception IllegalWriteException if the underlying
* implementation does not support modification
* @exception IllegalStateException if this Part is
* obtained from a READ_ONLY folder
*/
public void setContentMD5(String md5) throws MessagingException;
/**
* Get the language tags specified in the Content-Language header
* of this MimePart. The Content-Language header is defined by
* RFC 1766. Returns <code>null</code> if this header is not
* available.
*
* @return array of content language strings
* @exception MessagingException for failures
*/
public String[] getContentLanguage() throws MessagingException;
/**
* Set the Content-Language header of this MimePart. The
* Content-Language header is defined by RFC1766.
*
* @param languages array of language tags
* @exception IllegalWriteException if the underlying
* implementation does not support modification
* @exception IllegalStateException if this Part is
* obtained from a READ_ONLY folder
*/
public void setContentLanguage(String[] languages)
throws MessagingException;
/**
* Convenience method that sets the given String as this
* part's content, with a MIME type of "text/plain". If the
* string contains non US-ASCII characters. it will be encoded
* using the platform's default charset. The charset is also
* used to set the "charset" parameter. <p>
*
* Note that there may be a performance penalty if
* <code>text</code> is large, since this method may have
* to scan all the characters to determine what charset to
* use. <p>
*
* If the charset is already known, use the
* <code>setText</code> method that takes the charset parameter.
*
* @param text the text content to set
* @exception MessagingException if an error occurs
* @see #setText(String text, String charset)
*/
@Override
public void setText(String text) throws MessagingException;
/**
* Convenience method that sets the given String as this part's
* content, with a MIME type of "text/plain" and the specified
* charset. The given Unicode string will be charset-encoded
* using the specified charset. The charset is also used to set
* "charset" parameter.
*
* @param text the text content to set
* @param charset the charset to use for the text
* @exception MessagingException if an error occurs
*/
public void setText(String text, String charset)
throws MessagingException;
/**
* Convenience method that sets the given String as this part's
* content, with a primary MIME type of "text" and the specified
* MIME subtype. The given Unicode string will be charset-encoded
* using the specified charset. The charset is also used to set
* the "charset" parameter.
*
* @param text the text content to set
* @param charset the charset to use for the text
* @param subtype the MIME subtype to use (e.g., "html")
* @exception MessagingException if an error occurs
* @since JavaMail 1.4
*/
public void setText(String text, String charset, String subtype)
throws MessagingException;
}